Plumeria

https://github.com/zss-in-js/plumeria
Admin
Plumeria is a zero-cost, compile-time CSS-in-JS library for React that transforms type-safe styles...
Tokens:63,357
Snippets:900
Trust Score:5.7
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Dependencies

Source: https://github.com/zss-in-js/plumeria/blob/main/examples/example-react-router/README.md

Run this command to install the project dependencies.

```bash
npm install
```

--------------------------------

### Library package configuration

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/integration/component-library.mdx

Example package.json setup for a library, ensuring Plumeria is listed as a devDependency.

```json
{
  "name": "your-lib",
  "type": "module",
  "files": ["dist"],
  "exports": {
    ".": "./dist/index.js"
  },
  "peerDependencies": {
    "react": ">=18"
  },
  "devDependencies": {
    "@plumeria/core": "^18.1.2",
    "@plumeria/unplugin": "^18.1.2"
  }
}
```

--------------------------------

### Install project dependencies

Source: https://github.com/zss-in-js/plumeria/blob/main/examples/example-vite-qwik/README.md

Install the necessary packages using your preferred package manager.

```bash
$ npm install # or pnpm install or yarn install
```

--------------------------------

### Start development server

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/README.md

Run the local development environment for the documentation site.

```bash
pnpm dev
```

--------------------------------

### Install ESLint plugin and oxlint

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/getting-started/editor-integration.mdx

Install the required dependencies using your preferred package manager.

```sh
npm i --save-dev @plumeria/eslint-plugin oxlint
```

```sh
pnpm i --save-dev @plumeria/eslint-plugin oxlint
```

```sh
yarn add -D @plumeria/eslint-plugin oxlint
```

--------------------------------

### Install @plumeria/inspector

Source: https://github.com/zss-in-js/plumeria/blob/main/packages/inspector/README.md

Install the package as a development dependency using pnpm.

```bash
pnpm install -D @plumeria/inspector
```

--------------------------------

### Install @plumeria/unplugin

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/plugins/unplugin.mdx

Installation commands for various package managers.

```sh
npm i -D @plumeria/unplugin
```

```sh
yarn add -D @plumeria/unplugin
```

```sh
pnpm i -D @plumeria/unplugin
```

--------------------------------

### Example CSS Module input

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/codemod.mdx

A sample CSS module file before migration.

```css
.base { font-size: 12px }
.card { composes: base; padding: 16px }
.card:hover { background: teal }
.card .card-title { color: red }
```

--------------------------------

### Install @plumeria/core

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/getting-started/installation.mdx

Install the core type definitions package using your preferred package manager.

```sh
npm i -D @plumeria/core
```

```sh
yarn add -D @plumeria/core
```

```sh
pnpm i -D @plumeria/core
```

--------------------------------

### Install Plumeria ESLint Plugin and oxlint

Source: https://github.com/zss-in-js/plumeria/blob/main/packages/eslint-plugin/README.md

Install the required dependencies using npm or pnpm.

```bash
npm install -D @plumeria/eslint-plugin oxlint
# or
pnpm add -D @plumeria/eslint-plugin oxlint
```

--------------------------------

### Start Development Server

Source: https://github.com/zss-in-js/plumeria/blob/main/examples/example-react-router/README.md

Launch the development server with Hot Module Replacement enabled.

```bash
npm run dev
```

--------------------------------

### Install @plumeria/headlessui

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/components/headlessui.mdx

Commands to install the headless UI package using various package managers.

```sh
npm i @plumeria/headlessui
```

```sh
yarn add @plumeria/headlessui
```

```sh
pnpm i @plumeria/headlessui
```

--------------------------------

### Install @plumeria/next-plugin

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/plugins/next-plugin.mdx

Commands to install the plugin as a development dependency using various package managers.

```sh
npm i -D @plumeria/next-plugin
```

```sh
yarn add -D @plumeria/next-plugin
```

```sh
pnpm i -D @plumeria/next-plugin
```

--------------------------------

### Migration Report Example

Source: https://github.com/zss-in-js/plumeria/blob/main/packages/codemod/README.md

Example output showing how the codemod reports dynamic values and spread issues that prevent static conversion.

```text
src/Card.tsx
  8:5  dynamic-value
        The value of `color` cannot be represented statically.
  12:3  spread-create
        Top-level spreads cannot name a CSS Module class.
```

--------------------------------

### CSS module migration example

Source: https://github.com/zss-in-js/plumeria/blob/main/packages/codemod/README.md

Example of a CSS module file and its corresponding generated Plumeria styles and component usage.

```css
/* Card.module.css */
.base { font-size: 12px }
.card { composes: base; padding: 16px }
.card:hover { background: teal }
.card .card-title { color: red }
```

```ts
/* Card.styles.ts */
import * as css from '@plumeria/core';

export const styles = css.create({
  base: { fontSize: 12 },
  card: {
    ...css.marker('card', ':defined'),
    padding: 16,
    ':hover': { background: 'teal' },
  },
  cardTitle: {
    [css.extended('card', ':defined')]: { color: 'red' },
  },
});
```

```diff
/* Card.tsx */
+ import '@plumeria/core';
- import styles from './Card.module.css';
+ import { styles } from './Card.styles';

- <div className={styles.card}>
-   <span className={styles['card-title']} />
+ <div classStyle={[styles.base, styles.card]}>
+   <span classStyle={styles.cardTitle} />
  </div>
```

--------------------------------

### Initialize theme with createTheme

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/blog/plumeria-13-2.mdx

Example usage of createTheme with a class selector and theme properties.

```ts
const theme = css.createTheme(".dark"{
  primary: {
    default: 'skyblue',
    theme: 'yellow'
  }
})
```

--------------------------------

### Run the development server

Source: https://github.com/zss-in-js/plumeria/blob/main/examples/example-nextjs/README.md

Execute these commands in the terminal to start the local development environment.

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev
```

--------------------------------

### Example component migration

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/codemod.mdx

The diff showing how a component import and usage are updated.

```diff
+ import '@plumeria/core';
- import styles from './Card.module.css';
+ import { styles } from './Card.styles';

- <div className={styles.card}>
-   <span className={styles['card-title']} />
+ <div classStyle={[styles.base, styles.card]}>
+   <span classStyle={styles.cardTitle} />
  </div>
```

--------------------------------

### Install @plumeria/eslint-plugin

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/plugins/eslint-plugin/index.mdx

Install the plugin as a development dependency using your preferred package manager.

```sh
npm i --save-dev @plumeria/eslint-plugin
```

```sh
yarn add -D @plumeria/eslint-plugin
```

```sh
pnpm i --save-dev @plumeria/eslint-plugin
```

--------------------------------

### Apply styles with css.use

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/javascript/use.mdx

Example of using css.use to generate class name strings for external components.

```ts
import * as css from '@plumeria/core';

const styles = css.create({
  text: { fontSize: '16px' }
});

// Get the class name as a string
const className = css.use(styles.text);

// Apply to an external component
<ExternalComponent className={css.use(styles.text)} />
```

--------------------------------

### Macro usage example

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/getting-started/editor-integration.mdx

Demonstrates the expansion of the class shortcut into the classStyle macro.

```jsx
<div class /> -> Enter -> <div classStyle={|} />
```

--------------------------------

### Install Linting Dependencies

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/getting-started/installation.mdx

Install oxlint and rimraf to support the plumerialint command and build pipeline cleanup.

```sh
pnpm i -D oxlint rimraf
```

--------------------------------

### Install @plumeria/unplugin for Vite

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/getting-started/installation.mdx

Install the unplugin package for Vite integration.

```sh
npm i -D @plumeria/unplugin
```

```sh
yarn add -D @plumeria/unplugin
```

```sh
pnpm add -D @plumeria/unplugin
```

--------------------------------

### Install @plumeria/codemod

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/codemod.mdx

Install the package as a development dependency using various package managers.

```sh
npm i --save-dev @plumeria/codemod
```

```sh
yarn add -D @plumeria/codemod
```

```sh
pnpm i --save-dev @plumeria/codemod
```

--------------------------------

### Install Plumeria core package

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/getting-started/index.mdx

Install the @plumeria/core package as a development dependency using your preferred package manager.

```bash
npm install -D @plumeria/core
```

```bash
yarn add -D @plumeria/core
```

```bash
pnpm add -D @plumeria/core
```

--------------------------------

### Codemod execution output

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/blog/plumeria-18-0.mdx

Example output showing files modified and manual rename requirements.

```text
  plumeria.d.ts  2
  src/components/Card.tsx  3
  src/app/page.tsx  1

✔ renamed 6 occurrence(s) of "styleName" to "classStyle" in 3 file(s).

2 occurrence(s) need a manual rename — "styleName" is bound to a local name there:
  src/components/Card.tsx:12:24
  src/app/page.tsx:2:33
```

--------------------------------

### Install Plumeria Inspector

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/blog/plumeria-16-1.mdx

Add the inspector package to your project dependencies.

```sh
pnpm i @plumeria/inspector
```

--------------------------------

### Configure Bundlers

Source: https://github.com/zss-in-js/plumeria/blob/main/packages/unplugin/README.md

Examples of registering the Plumeria plugin in various bundler configuration files.

```javascript
//vite.config.js
import { defineConfig } from 'vite';
import plumeria from '@plumeria/unplugin';

export default defineConfig({ 
  plugins: [ 
    plumeria.vite(), 
  ],
});
```

```javascript
// webpack.config.js
import plumeria from '@plumeria/unplugin';

export default { 
  plugins: [ 
    plumeria.webpack(), 
  ],
};
```

```javascript
// rspack.config.js
import plumeria from '@plumeria/unplugin';

export default  { 
  plugins: [ 
    plumeria.rspack(), 
  ],
};
```

```javascript
// farm.config.js
import { defineConfig } from '@farmfe/core';
import plumeria from '@plumeria/unplugin';

export default defineConfig({ 
  plugins: [ 
    plumeria.farm({ devEmitToDisk: true }), 
  ],
});
```

```javascript
// build.js
import { build } from 'esbuild';
import plumeria from '@plumeria/unplugin';

build({ 
  entryPoints: ['src/index.tsx'], 
  bundle: true, 
  outfile: 'dist/out.js', 
  plugins: [ 
    plumeria.esbuild(), 
  ],
}).catch(() => process.exit(1));
```

```javascript
// rollup.config.js
import plumeria from '@plumeria/unplugin';
export default {
  input: 'src/index.tsx',
  plugins: [
    plumeria.rollup(),
  ],
};
```

```javascript
// rolldown.config.js
import plumeria from '@plumeria/unplugin';
export default {
  input: 'src/index.tsx',
  plugins: [
    plumeria.rolldown(),
  ],
};
```

```javascript
// build.js
import plumeria from '@plumeria/unplugin';
await Bun.build({
  entrypoints: ['./src/index.tsx'],
  outdir: './dist',
  plugins: [
    plumeria.bun(),
  ],
});
```

--------------------------------

### Implement createTheme API

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/blog/plumeria-13-0.mdx

Example of using the redesigned createTheme API to define theme-specific values for a selector.

```ts
import * as css from '@plumeria/core';
// Here, we're passing the standard Tailwind theme, .dark, as an example.
export const theme = css.createTheme('.dark', {
  text: {
    default: '#333', // Default value (light mode, etc.)
    theme: '#eaeaea',  // Value when the selector (.dark) is applied
  },
  background: {
    default: 'white',
    theme: 'black',
  }
});
```

--------------------------------

### Run codemod commands

Source: https://github.com/zss-in-js/plumeria/blob/main/packages/codemod/README.md

Execute migration or refactoring commands using npx without requiring a local installation.

```sh
npx @plumeria/codemod migrate --from css-modules
npx @plumeria/codemod migrate --from plumeria
npx @plumeria/codemod rename-prop classStyle sx
```

--------------------------------

### Configure Rspack

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/integration/rspack.mdx

Example configuration for rspack.config.js integrating @plumeria/unplugin with SWC loader and React Refresh.

```ts
import { rspack } from '@rspack/core';
import { ReactRefreshRspackPlugin } from '@rspack/plugin-react-refresh';
import plumeria from '@plumeria/unplugin';

const isDev = process.env.NODE_ENV === 'development';

export default {
  entry: './src/index.tsx',
  output: {
    filename: 'bundle.js',
    clean: true,
  },
  resolve: {
    extensions: ['.ts', '.tsx', '.js'],
  },
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            jsc: {
              parser: { syntax: 'typescript', tsx: true },
              transform: {
                react: {
                  runtime: 'automatic',
                  development: isDev,
                  refresh: isDev,
                },
              },
            },
          },
        },
      },
    ],
  },
  plugins: [
    plumeria.rspack(),
    new rspack.HtmlRspackPlugin({ template: './src/index.html' }),
    isDev && new ReactRefreshRspackPlugin(),
  ].filter(Boolean),
  devServer: {
    hot: true,
    port: 3000,
  },
};
```

--------------------------------

### Dry run output example

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/codemod.mdx

The console output displayed during a dry run.

```text
  src/Card.module.css  ->  src/Card.styles.ts

1 stylesheet(s) would be converted, 1 consumer(s) rewritten.
Run without --dry-run to apply.
```

--------------------------------

### Implement Accordion Component

Source: https://github.com/zss-in-js/plumeria/blob/main/packages/headlessui/README.md

Example showing how to use the Accordion component with Plumeria's classStyle abstraction.

```tsx
import * as css from '@plumeria/core';
import { Accordion } from '@plumeria/headlessui';

const styles = css.create({
  root: {
    width: '100%',
    overflow: 'hidden',
    border: '1px solid #e4e4e7',
    borderRadius: '8px',
  },
  trigger: {
    display: 'flex',
    flex: 1,
    alignItems: 'center',
    justifyContent: 'space-between',
    padding: '14px 18px',
    fontSize: '14px',
    fontWeight: '600',
    cursor: 'pointer',
    backgroundColor: 'transparent',
    border: 'none',
  },
  content: {
    padding: '14px 18px',
    fontSize: '13.5px',
    borderTop: '1px solid #e4e4e7',
  },
});

export const FAQ = () => (
  <Accordion type="single" collapsible classStyle={styles.root}>
    <Accordion.Item value="item-1">
      <Accordion.Header>
        <Accordion.Trigger classStyle={styles.trigger}>
          Is it accessible?
        </Accordion.Trigger>
      </Accordion.Header>
      <Accordion.Content classStyle={styles.content}>
        Yes. It adheres to the WAI-ARIA design pattern.
      </Accordion.Content>
    </Accordion.Item>
  </Accordion>
);
```

--------------------------------

### Define static breakpoints

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/javascript/createStatic.mdx

Example of defining media query breakpoints using createStatic.

```ts
import * as css from '@plumeria/core';

export const breakpoints = css.createStatic({
  xs: '@media (max-width: 480px)',
  sm: '@media (max-width: 640px)',
  md: '@media (max-width: 768px)',
  lg: '@media (max-width: 1024px)',
  xl: '@media (max-width: 1280px)',
});
```

--------------------------------

### Example migration transformation

Source: https://github.com/zss-in-js/plumeria/blob/main/packages/codemod/README.md

Shows the transformation from a Plumeria component to a CSS Module and updated React component.

```tsx
/* Card.tsx — before */
import * as css from '@plumeria/core';

export const styles = css.create({
  base: { fontSize: 12 },
  card: {
    padding: 16,
    ':hover': { background: 'teal' },
  },
  size: (width: number) => ({ width }),
});

export function Card({ width }: { width: number }) {
  return <div classStyle={[styles.base, styles.card, styles.size(width)]} />;
}
```

```css
/* Card.module.css — generated */
.base { font-size: 12px }
.card { padding: 16px }
.card:hover { background: teal }
.size { width: var(--styles-size-width) }
```

```diff
/* Card.tsx — after */
- import * as css from '@plumeria/core';
+ import styles from './Card.module.css';
+ export { styles };

- export const styles = css.create({
-   base: { fontSize: 12 },
-   card: {
-     padding: 16,
-     ':hover': { background: 'teal' },
-   },
-   size: (width: number) => ({ width }),
- });

  export function Card({ width }: { width: number }) {
-   return <div classStyle={[styles.base, styles.card, styles.size(width)]} />;
+   return (
+     <div
+       className={[styles.base, styles.card, styles.size].join(' ')}
+       style={{ ['--styles-size-width' as string]: width }}
+     />
+   );
  }
```

--------------------------------

### Example CSS Module input and generated TypeScript output

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/blog/plumeria-18-2.mdx

Demonstrates the transformation of a CSS module file into a Plumeria styles object.

```css
/* Card.module.css */
.base { font-size: 12px }
.card { composes: base; padding: 16px }
.card:hover { background: teal }
.card .card-title { color: red }
```

```ts
/* Card.styles.ts */
import * as css from '@plumeria/core';

export const styles = css.create({
  base: { fontSize: 12 },
  card: {
    ...css.marker('card', ':defined'),
    padding: 16,
    ':hover': { background: 'teal' },
  },
  cardTitle: {
    [css.extended('card', ':defined')]: { color: 'red' },
  },
});
```

--------------------------------

### Implement custom view transition

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/javascript/viewTransition.mdx

Example of defining a custom cross-fade animation using keyframes and applying it to a CSS class.

```ts
import * as css from '@plumeria/core';

const fadeIn = css.keyframes({
  from: { opacity: 0 },
  to: { opacity: 1 },
});

const fadeOut = css.keyframes({
  from: { opacity: 1 },
  to: { opacity: 0 },
});

const longCrossFade = css.viewTransition({
  old: {
    animationName: fadeOut,
    animationDuration: '1.2s',
  },
  new: {
    animationName: fadeIn,
    animationDuration: '1.2s',
  },
});

export const transition = css.create({
  name: {
    viewTransitionName: longCrossFade,
  },
});
```

```css
@keyframes kf-x34h9adh {
  from {
    opacity: 0;
  }

  to {
    opacity: 1;
  }
}

@keyframes kf-xmzotw7h {
  from {
    opacity: 1;
  }

  to {
    opacity: 0;
  }
}

::view-transition-old(vt-xsq18f68) {
  animation-name: kf-xmzotw7h;
  animation-duration: 1.2s;
}

::view-transition-new(vt-xsq18f68) {
  animation-name: kf-x34h9adh;
  animation-duration: 1.2s;
}

.xa6j6hgv {
  view-transition-name: vt-xjp967de;
}
```

--------------------------------

### Example of Plumeria to CSS Modules transformation

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/blog/plumeria-18-2.mdx

Shows the diff of a component migration, including import changes and the conversion of dynamic style functions to CSS variables.

```diff
/* Card.tsx */
- import * as css from '@plumeria/core';
+ import styles from './Card.module.css';
+ export { styles };

- export const styles = css.create({
-   card: { padding: 16 },
-   size: (width: number) => ({ width }),
- });

  export const Card = ({ width }: { width: number }) => (
-   <div classStyle={[styles.card, styles.size(width)]} />
+   <div
+     className={[styles.card, styles.size].join(' ')}
+     style={{ ['--styles-size-width' as string]: typeof width === 'number' ? `${width}px` : width }}
+   />
  );
```

--------------------------------

### Media Query Theme Selector

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/javascript/createTheme.mdx

Example of using a media query for system-level theme switching, along with its compiled CSS output.

```ts
import * as css from '@plumeria/core';

export const theme = css.createTheme('@media (prefers-color-scheme: dark)', {
  text: {
    default: '#333',
    theme: '#eaeaea',
  },
});
```

```css
:where(:root) {
  --xkktl0fl-text: #333;
}

@media (prefers-color-scheme: dark) {
  :where(:root) {
    --xkktl0fl-text: #eaeaea;
  }
}
```

--------------------------------

### Example Plumeria component and generated CSS

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/codemod.mdx

A source component using css.create and the resulting CSS module output.

```tsx
import * as css from '@plumeria/core';

export const styles = css.create({
  base: { fontSize: 12 },
  card: {
    padding: 16,
    ':hover': { background: 'teal' },
  },
  size: (width: number) => ({ width }),
});

export function Card({ width }: { width: number }) {
  return <div classStyle={[styles.base, styles.card, styles.size(width)]} />;
}
```

```css
.base {
  font-size: 12px;
}

.card {
  padding: 16px;
}

.card:hover {
  background: teal;
}

.size {
  width: var(--styles-size-width);
}
```

--------------------------------

### Configure Vite plugins

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/blog/plumeria-15-1.mdx

Example of Vite plugin ordering that previously caused issues with Plumeria's parser.

```ts
export default defineConfig({
  plugins: [react(), plumeria.vite()],
});
```

--------------------------------

### Initialize Astro Project

Source: https://github.com/zss-in-js/plumeria/blob/main/examples/example-vite-astro-ts/README.md

Use this command to scaffold a new project using the basics template.

```sh
npm create astro@latest -- --template basics
```

--------------------------------

### Build for Production

Source: https://github.com/zss-in-js/plumeria/blob/main/examples/example-react-router/README.md

Generate a production-ready build of the application.

```bash
npm run build
```

--------------------------------

### Install oxlint dependency

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/blog/plumeria-2-2-0.mdx

Required dev dependency installation for the updated plumerialint command.

```sh
pnpm install -D oxlint
```

--------------------------------

### Run the migration command

Source: https://github.com/zss-in-js/plumeria/blob/main/packages/codemod/README.md

Execute the migration from Plumeria to CSS Modules using npx.

```sh
npx @plumeria/codemod migrate --from plumeria [paths...]
```

--------------------------------

### Prop Rename Diff Examples

Source: https://github.com/zss-in-js/plumeria/blob/main/packages/codemod/README.md

Examples of how the rename-prop command updates JSX attributes and TypeScript interface signatures.

```diff
- <div classStyle={styles.card} />
+ <div sx={styles.card} />
```

```diff
  interface CardProps {
-   classStyle?: Style;
+   sx?: Style;
  }
```

--------------------------------

### Configure ESLint recommended settings

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/plugins/eslint-plugin/index.mdx

Import the plugin and add the recommended configuration to your ESLint export.

```js
import plumeria from '@plumeria/eslint-plugin';

export default [plumeria.configs.recommended];
```

--------------------------------

### Destructured property example

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/blog/plumeria-18-0.mdx

Example of a site where the codemod identifies manual intervention is required due to local binding.

```tsx
const Card = ({ styleName }) => <div styleName={styleName} />;
```

--------------------------------

### Compiled output example

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/javascript/create.mdx

The resulting JSX output after bundler processing.

```tsx
<div className="xxp6epoh xwbwwha1 xbief8v4 xzllkng3" />
```

--------------------------------

### Handling multiple css.create calls

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/codemod.mdx

Demonstrates how the codemod handles multiple style definitions in a single file by renaming keys.

```diff
- const styles = css.create({ base: { color: 'red' } });
- const hoverStyles = css.create({ base: { color: 'blue' } });
+ import styles from './Button.module.css';

  export const Button = () => (
-   <a classStyle={[styles.base, hoverStyles.base]} />
+   <a className={styles.baseHoverStylesBase} />
  );
```

--------------------------------

### Configure no-physical-properties and no-logical-properties rules

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/plugins/eslint-plugin/optional-rules.mdx

Basic configuration for enabling the physical and logical property naming rules.

```js
'@plumeria/no-physical-properties': 'warn'
// paddingLeft → rename to paddingInlineStart

'@plumeria/no-logical-properties': 'warn'
// paddingInlineStart → rename to paddingLeft
```

--------------------------------

### Configure Plugin Options

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/integration/vite.mdx

Advanced configuration using include, exclude, and styleProp options.

```ts
export default defineConfig({
  plugins: [
    plumeria.vite({
      include: ['./src/**/*.{ts,tsx}'],
      exclude: ['**/node_modules/**'],
      styleProp: 'sx',
    }),
  ],
});
```

--------------------------------

### Forbidden combinator syntax

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/blog/plumeria-7-0-0.mdx

Example of syntax that triggers the eslint no-combinator rule.

```ts
":hover > div": {...} // Error
```

--------------------------------

### Invoke the Button component

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/blog/plumeria-0-27-0.mdx

Example usage of the Button component with a color prop.

```tsx
<Button color="key">
```

--------------------------------

### Migrate css.props to css.use

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/blog/plumeria-9-0-0.mdx

Shows the transition from the deprecated 8.x syntax to the new 9.0.0 API.

```tsx
import * as css from '@plumeria/core';

<div className={css.props(styles.featureCard)} />
```

```tsx
import * as css from '@plumeria/core';

const styles = css.create({...});

<div className={css.use(styles.featureCard)} />
```

--------------------------------

### Dry run migration

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/codemod.mdx

Preview the migration changes without modifying files.

```sh
npx @plumeria/codemod migrate --from css-modules --dry-run
```

--------------------------------

### Example Plumeria styles output

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/codemod.mdx

The resulting TypeScript file after migrating the CSS module.

```ts
import * as css from '@plumeria/core';

export const styles = css.create({
  base: { fontSize: 12 },
  card: {
    ...css.marker('card', ':defined'),
    padding: 16,
    ':hover': { background: 'teal' },
  },
  cardTitle: {
    [css.extended('card', ':defined')]: { color: 'red' },
  },
});
```

--------------------------------

### Apply styles with classStyle

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/javascript/use.mdx

Example of using the classStyle prop with conditional array values.

```tsx
import * as css from '@plumeria/core';

const styles = css.create({
  base: { color: 'red' },
  active: { fontWeight: 'bold' }
});

function Component({ active }) {
  return (
    <div classStyle={[styles.base, active && styles.active]}>
      Hello
    </div>
  );
}
```

--------------------------------

### Run plumerialint CLI

Source: https://github.com/zss-in-js/plumeria/blob/main/packages/eslint-plugin/README.md

Execute the linting process via the command line.

```bash
plumerialint
```

--------------------------------

### Create atomic styles with Plumeria

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/blog/plumeria-0-13-0.mdx

Demonstrates the usage of css.create to generate atomic class names and css.props to retrieve them.

```ts
import { css } from '@plumeria/core';

const styles = css.create({
  text: {
    fontSize: 12, // xxxhash1
    color: 'navy', // xxxhash2
  },
});

const className = styles.$text;
// className is "xxxhash1 xxxhash2"

const classNames = css.props(styles.text); // if you want to apply more styles
// classNames is "xxxhash1 xxxhash2
```

--------------------------------

### Production Build Structure

Source: https://github.com/zss-in-js/plumeria/blob/main/examples/example-react-router/README.md

Visual representation of the directory structure after running the build command.

```text
├── package.json
├── package-lock.json (or pnpm-lock.yaml, or bun.lockb)
├── build/
│   ├── client/    # Static assets
│   └── server/    # Server-side code
```

--------------------------------

### Importing pseudo-classes

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/blog/plumeria-0-10-4.mdx

Import the ps utility from @plumeria/core to use pseudo-classes in styles.

```ts
import { css, ps } from '@plumeria/core';
```

--------------------------------

### Generated CSS for markers and extended styles

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/codemod.mdx

Example of how css.marker and css.extended are compiled into container queries.

```css
.grand:hover {
  --xl0a2l54-grand-hover: 1;
}

@container style(--xl0a2l54-grand-hover: 1) {
  .child {
    color: #0066cc;
  }
}
```

--------------------------------

### Configure recommended rules in ESLint

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/plugins/eslint-plugin/optional-rules.mdx

Add the recommended configuration and optional rules to your ESLint configuration file.

```js
import plumeria from '@plumeria/eslint-plugin';

export default [
  plumeria.configs.recommended,
  {
    rules: {
      '@plumeria/expand-border-shorthands': 'warn',
      '@plumeria/no-logical-properties': 'warn',
    },
  },
];
```

--------------------------------

### Prohibited Inline Object Usage

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/blog/plumeria-10-5.mdx

Examples of syntax that will now trigger an error due to the no-inline-object rule.

```tsx
<div styleName={{ color: 'red' }} />
<div styleName={{ [styles.active]: isActive }} />
```

--------------------------------

### Build script for library distribution

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/integration/component-library.mdx

An esbuild configuration that bundles the library and manually injects the CSS import into the output file.

```js
import esbuild from 'esbuild';
import fs from 'node:fs';
import plumeria from '@plumeria/unplugin';

await esbuild.build({
  entryPoints: ['src/index.tsx'],
  bundle: true,
  outfile: 'dist/index.js',
  external: ['react', 'react/jsx-runtime'],
  plugins: [plumeria.esbuild({ include: /\.[jt]sx?$/ })],
  loader: { '.tsx': 'tsx', '.ts': 'ts' },
  format: 'esm',
  jsx: 'automatic',
});

fs.writeFileSync(
  'dist/index.js',
  `import './index.css';\n${fs.readFileSync('dist/index.js', 'utf-8')}`,
);
```

--------------------------------

### Implement viewTransition with CSS

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/blog/plumeria-0-19-0.mdx

Demonstrates creating a cross-fade transition using keyframes and applying it to a component via viewTransition.

```tsx
import { css } from '@plumeria/core';

const fadeOut = css.keyframes({
  to: { opacity: 0 },
});

const fadeIn = css.keyframes({
  from: { opacity: 0 },
});

const longCrossFade = css.viewTransition({
  old: {
    animation: fadeOut,
    animationDuration: '2s',
  },
  new: {
    animation: fadeIn,
    animationDuration: '2s',
  },
});

export const transition = css.create({
  name: {
    viewTransitionName: longCrossFade,
  },
});

<ViewTransition name={transition.name}>
  {/* ... */}
</ViewTransition>
```

--------------------------------

### Forbidden Styling Patterns

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/ai.md

Examples of patterns that break static analysis or cause runtime errors in Plumeria.

```tsx
<span classStyle={{ fontSize: '12px' }}>Small Text</span>
```

```tsx
export const BadComponent = ({ dynamicColor }) => {
  const dynamicStyles = css.create({
    dynamic: { color: dynamicColor },
  });
  // ...
};
```

```tsx
<span className="global-class" classStyle={styles.base}>Text</span>
```

--------------------------------

### Support for modern CSS pseudo-selectors

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/blog/plumeria-16-2.mdx

Example usage of updated pseudo-selector validation for modern CSS features.

```tsx
css.create({
  input: {
    '::file-selector-button': { backgroundColor: 'purple' },
  },
  popover: {
    ':popover-open': { boxShadow: '0 4px 12px rgba(0,0,0,0.1)' },
  },
});
```

--------------------------------

### Configure plugin options

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/plugins/next-plugin.mdx

Pass custom compiler options to the withPlumeria wrapper.

```ts
export default withPlumeria(nextConfig, {
  include: ['./src/**/*.{ts,tsx}'],
  exclude: ['**/node_modules/**', '**/.next/**'],
  styleProp: 'sx',
});
```

--------------------------------

### Manual Rename Report

Source: https://github.com/zss-in-js/plumeria/blob/main/packages/codemod/README.md

Example output for instances where the codemod cannot automatically rename a prop due to local binding.

```text
2 occurrence(s) need a manual rename — "classStyle" is bound to a local name there:
  src/components/Card.tsx:8:12
  src/components/Card.tsx:14:22
```

--------------------------------

### Report naming conflict

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/codemod.mdx

Example of the error message displayed when attempting to use a reserved React prop name.

```text
✖ "style" is already used by React
```

--------------------------------

### Bundler Plugin Initialization

Source: https://github.com/zss-in-js/plumeria/blob/main/packages/unplugin/README.md

Methods to initialize the Plumeria plugin within various bundler configuration files.

```APIDOC
## Bundler Plugin Methods

### Description
Register the Plumeria plugin by calling the corresponding method for your bundler in its configuration file.

### Methods
- `plumeria.vite(options)`
- `plumeria.webpack(options)`
- `plumeria.rspack(options)`
- `plumeria.farm(options)`
- `plumeria.esbuild(options)`
- `plumeria.rollup(options)`
- `plumeria.rolldown(options)`
- `plumeria.bun(options)`

### Options
- **include** (string[]) - Optional - Files to transform (default: `ts/tsx/js/jsx`)
- **exclude** (string[]) - Optional - Files to skip
- **devEmitToDisk** (boolean) - Optional - Write CSS to disk in development for HMR (default: `false`)
- **styleProp** (string) - Optional - The JSX prop that carries styles (default: `'classStyle'`)
```

--------------------------------

### Comparing Import Methods

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/blog/plumeria-7-2-0.mdx

Shows the transition from traditional namespace imports to the new default import syntax enabled in v7.2.0.

```typescript
// Traditional method (any name namespace import)
import * as css from '@plumeria/core';

// New method (any name default import)
import css from '@plumeria/core';
```

--------------------------------

### Attribute-based Theme Selector

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/javascript/createTheme.mdx

Example of using an attribute selector for theme configuration, along with its compiled CSS output.

```ts
import * as css from '@plumeria/core';

export const theme = css.createTheme('[data-theme="dark"]', {
  text: {
    default: '#333',
    theme: '#eaeaea',
  },
});
```

```css
:where(:root) {
  --xkktl0fl-text: #333;
}

[data-theme="dark"] {
  --xkktl0fl-text: #eaeaea;
}
```

--------------------------------

### Docker Deployment Commands

Source: https://github.com/zss-in-js/plumeria/blob/main/examples/example-react-router/README.md

Commands to build and run the application within a Docker container.

```bash
docker build -t my-app .

# Run the container
docker run -p 3000:3000 my-app
```

--------------------------------

### Class-based Theme Selector

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/javascript/createTheme.mdx

Example of using a class selector for theme toggling, along with its compiled CSS output.

```ts
import * as css from '@plumeria/core';

export const theme = css.createTheme('.dark', {
  text: {
    default: '#333',
    theme: '#eaeaea',
  },
});
```

```css
:where(:root) {
  --xkktl0fl-text: #333;
}

.dark {
  --xkktl0fl-text: #eaeaea;
}
```

--------------------------------

### Configure package.json Scripts

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/getting-started/installation.mdx

Define build and development scripts for Next.js and Vite projects to integrate plumerialint.

```json
  "scripts": {
    "predev": "rimraf .next",
    "prebuild": "rimraf .next",
    "dev": "next dev",
    "build": "plumerialint -- next build",
    "start": "next start",
  },
```

```json
  "scripts": {
    "dev": "vite",
    "build": "plumerialint -- tsc -b && vite build", 
  },
```

--------------------------------

### Conditional style prop application

Source: https://github.com/zss-in-js/plumeria/blob/main/RELEASENOTE.md

Examples of valid classStyle syntax that ensure styles are correctly carried through conditions.

```javascript
classStyle={[styles.base, cond && styleArray]}
```

```javascript
classStyle={cond ? styleArray : styles.base}
```

--------------------------------

### Configure next.config.ts

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/plugins/next-plugin.mdx

Wrap the Next.js configuration object with withPlumeria to enable the plugin.

```ts
import type { NextConfig } from "next";
import { withPlumeria } from "@plumeria/next-plugin";

const nextConfig: NextConfig = {
  // Existing configuration
};

export default withPlumeria(nextConfig);
```

--------------------------------

### Configure package exports

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/blog/plumeria-7-4-0.mdx

Define the entry points for types and imports in the package.json file.

```json
  "exports": {
    ".": {
      "types": "./lib/css.d.ts",
      "import": "./lib/css.js"
    }
  },
```

--------------------------------

### Expand Border Shorthand Transformation

Source: https://github.com/zss-in-js/plumeria/blob/main/packages/eslint-plugin/README.md

Example of how the expand-border-shorthands rule transforms a border shorthand property into its individual longhand components.

```js
borderTop: '1px solid red'
// becomes
borderTopWidth: '1px', borderTopStyle: 'solid', borderTopColor: 'red'
```

--------------------------------

### Identify destructured and object-bound props

Source: https://github.com/zss-in-js/plumeria/blob/main/docs/content/docs/api-reference/codemod.mdx

Examples of prop usage where the codemod identifies local bindings that require manual review.

```tsx
const Card = ({ classStyle }: CardProps) => <div classStyle={classStyle} />;

const Panel = (props: CardProps) => <section classStyle={props.classStyle} />;
```
Tokens:
Raw