# @frontfriend/tailwind

Changelog for the @frontfriend/tailwind package

# @frontfriend/tailwind Changelog

All notable changes to the @frontfriend/tailwind package will be documented in this page.

## [@frontfriend/tailwind] v4.0.0 - 2026-06-14

### Breaking changes

- **CLI `add` command removed** - `npx frontfriend add page <id>` and `npx frontfriend add project <id>` no longer exist. Use `npx frontfriend download` to pull restyled components instead.

### Migration Guide

- Continue using `npx frontfriend init` to sync design tokens into Tailwind v4.
- Use `npx frontfriend download <components...>` to add restyled shadcn-style components to your project.
- Any workflow that relied on `frontfriend add` (page/project export) is no longer supported; build pages directly from the downloaded components.

## [@frontfriend/tailwind] v3.0.4 - 2026-03-22

### Fixed
- **Turbopack CSS Parsing: `file:` Variant Classes in Safelist** - Safelisted classes with `file:` prefix caused Turbopack to crash with invalid chained pseudo-element selectors like `::placeholder::file-selector-button`
  - Added defensive `file:` class filter in plugin safelist merge and CLI class extraction
  - New caches from `npx frontfriend init` no longer contain `file:` entries; existing caches are filtered at runtime
  - **Impact**: Next.js 16+ apps with Turbopack no longer crash on page load from `file:` variant safelist entries

## [@frontfriend/tailwind] v3.0.3 - 2026-01-15

### Added
- **Page Main Padding Utilities** - New utility classes for consistent page content padding
  - `.px-ff-main` - Applies horizontal padding using `var(--ff-main-px)`
  - `.py-ff-main` - Applies vertical padding using `var(--ff-main-py)`
  - `.p-ff-main` - Applies both horizontal and vertical padding
  - Values are defined per-project in `custom.css` with responsive breakpoints

**Usage:** Projects define CSS variables in their `custom.css`, then use `px-main py-main` classes for consistent responsive padding without memorizing values.

## [@frontfriend/tailwind] v3.0.2 - 2026-01-09

### Fixed
- **Build Compatibility** - Fixed build errors in Storybook and other browser-based tools
  - Resolved "top-level await not available" error during builds
  - Package now works correctly in all build environments (Vite, Webpack, esbuild)

**Who this affects:** If you saw build errors mentioning "top-level await" when building your project, this update fixes that.

## [@frontfriend/tailwind] v3.0.1 - 2026-01-08

### Fixed
- **ESM Import Support** - Fixed issue where ESM imports returned empty objects in `.mjs` Tailwind config files
  - You can now safely use `import plugin from '@frontfriend/tailwind'` in `tailwind.config.mjs`
  - Accessing `plugin({}).config.safelist` now works correctly in ESM configs
  - Both `import` (ESM) and `require` (CommonJS) now work identically

**Who this affects:** If you're using `tailwind.config.mjs` (ESM format) and were getting `undefined` when accessing the plugin's config, this update fixes that issue.

## [@frontfriend/tailwind] v3.0.0 - 2025-12-01

### Added
- **Tag-Based Version Resolution** - Full support for design system versioning with tags
  - Added `tag` parameter support in `frontfriend.config.js` (e.g., `"tag": "dev"`)
  - CLI now fetches tag-specific token versions from API
- Enhanced cache management for tag-specific token versions
- Version resolution logic for dev/next/latest tags

### Changed
- **Breaking**: Default behavior without tag parameter now resolves to 'latest' tag instead of most recent version

### Migration Guide

Projects using `@frontfriend/tailwind` can optionally update their `frontfriend.config.js` to specify which tag to use:

```js
export default {
  "ff-id": "your-ff-id",
  "tag": "dev", // Optional: specify which tag to use (dev/next/latest)
  "aliases": {
    "ui": "@/components/ui"
  }
};
```

**Backward Compatibility:**
- If no `tag` is specified, the plugin will use the `latest` tag by default
- Existing projects without the `tag` parameter will continue to work without any changes
- The `latest` tag points to your stable production version

### Fixed
- **Windows compatibility** - Fixed BOM encoding issue preventing custom CSS/JS files from loading on Windows

## [@frontfriend/tailwind] v2.6.0 - 2025-12-15

### Added

- Fixed React components re-rendering unnecessarily when using `config` in hooks
- Configuration now works with `Object.keys()` and spread operator `{...config}`
- Deep property access never crashes - safe for SSR and Next.js builds
- 10x faster performance for repeated property access

### Changed

- No more "Cannot read property 'x' of undefined" errors during builds
- To check if a property exists, use `'property' in config` instead of checking for `undefined`

## [@frontfriend/tailwind] v2.5.4 - 2025-11-14

### Fixed
- **HSL Color Rendering in CSS Variables** - CSS variables for colors now contain complete, valid color values
  - Updated semantic variable processing to wrap HSL component values in `hsl()` function
  - Added regex detection for HSL format values (e.g., `206 92% 5% / 0.9`)
  - Applied to both light and dark mode CSS variable generation
  - Utilities like `bg-overlay-strong` now render correctly with proper alpha transparency

## [@frontfriend/tailwind] v2.5.3 - 2025-10-30

### Fixed
- **Turbopack Module Resolution** - Fixed `config` and `ffdc` exports being `undefined` with Next.js `--turbopack` flag
  - Updated `next.js` wrapper to inject config via `env` field for Turbopack compatibility
  - Both webpack (DefinePlugin) and Turbopack (env vars) are now supported
- **Turbopack Compatibility** - Fixed CSS parsing errors with Next.js 15.3+ `--turbopack` flag
  - Removed variant generation from safelist to prevent invalid CSS selector combinations
  - Fixed issue where Turbopack's strict CSS parser rejected selectors like `.file\:placeholder\:text-neutral-subtle::-moz-placeholder::file-selector-button`
  - Safelist now only includes base classes (e.g., `bg-brand-mid` instead of `hover:bg-brand-mid`)
  - Tailwind's JIT still detects and generates variant classes when actually used in components
  - **Impact**: Users can now use Next.js with `--turbopack` flag without CSS parsing errors
  - **Breaking Changes**: None - all variant functionality preserved via JIT detection

## [@frontfriend/tailwind] v2.5.0 - 2025-08-31

### Added
- **New CLI Commands** - `npx frontfriend add` for importing generated pages and projects
  - `npx frontfriend add page <id>` - Add a single page from Frontfriend platform
  - `npx frontfriend add project <id>` - Add all pages from a project
  - Options: `--name`, `--path`, `--force`, `--pages` for fine-grained control
- **Export Integration** - CLI now fetches pages/projects via new export API endpoints
- **Automatic UI Component Detection** - Downloads required UI components when adding pages
- **Project Import Support** - Batch import multiple pages from a project with a single command

### Changed
- Enhanced CLI with better error handling and progress indicators
- Improved component download workflow integration

## [@frontfriend/tailwind] v2.4.2 - 2025-08-27

### Fixed
- Fixed safelist generation in fallback mode (when ff-id is not found on server)
- Updated client-side token processor to generate safelist from semantic tokens instead of raw colorMap
- Safelist now properly includes bg-, text-, border-, layer-, overlay-, and icon- utilities
- Fixed safelist combination logic to properly merge and deduplicate classes
- Trial plan download cli fixed

### Changed
- Client-side safelist generation now mirrors server-side logic for consistency
- Improved safelist generation to focus on semantic tokens rather than raw colors

## [@frontfriend/tailwind] v2.4.0 - 2025-08-25

### Added
- Backward compatibility for automatic cls to safelist migration
- Debug logging for safelist in CLI

### Changed
- Renamed cls to safelist throughout codebase for improved clarity
- Updated cache manager to handle safelist array correctly
- Improved safelist processing architecture

### Fixed
- Safelist caching now properly saves classes with brackets like `[&::-webkit-search-cancel-button]:hidden`

## [@frontfriend/tailwind] v2.1.6 - 2025-01-16

### Added
- Type checking support for Vue applications with `vue-tsc`
- Unified plugin naming across Vite and Next.js integrations
- `types: boolean` option in frontfriend.config.js to enable type generation

### Changed
- **Breaking**: Plugin exports renamed for consistency:
  - Vite plugin: `frontfriendPlugin` → `frontfriend`
  - Next.js plugin: `withFrontFriend` → `frontfriend`
- Type generation output path can be customized via `aliases.types`
- `ffdc` function now handles null/undefined configs gracefully
- Improved TypeScript type definitions for better IDE support

### Fixed
- Resolved type checking errors in Vue applications
- Fixed missing `useBreakpoints` export in Vue utilities
- Corrected Vite plugin import patterns for both named and default exports


### Migration Guide

Update your Vite configuration:
```js
// Before
import { frontfriendPlugin } from '@frontfriend/tailwind/vite'
export default defineConfig({
  plugins: [vue(), frontfriendPlugin()]
})

// After
import frontfriend from '@frontfriend/tailwind/vite'
export default defineConfig({
  plugins: [vue(), frontfriend()]
})
```

Update your Next.js configuration:
```js
// Before
const withFrontFriend = require('@frontfriend/tailwind/next')
module.exports = withFrontFriend(nextConfig)

// After
const frontfriend = require('@frontfriend/tailwind/next')
module.exports = frontfriend(nextConfig)
```

### Enable types generation
```js
// frontfriend.config.js
export default {
  "ff-id": "your-project-id",
  "types": true,                         // Enable type generation (default: false)
  "aliases": {
    "ui": "@/src/components/ui",
    "types": "src/types/"                // Custom types directory (optional)
  }
}
```

When `types` is enabled:
- Types will be generated in `types/frontfriend.d.ts` by default
- If `aliases.types` is defined, types will be generated in `{aliases.types}/frontfriend.d.ts`


*The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).*