### Install and Run Next.js Example

Source: https://github.com/digitecgalaxus/next-yak/blob/main/examples/next-js/README.md

Install dependencies, build the project using either SWC or the default build, and then run the example application.

```bash
pnpm install
pnpm build && pnpm build:swc
pnpm example
```

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

### Run Vite example

Source: https://github.com/digitecgalaxus/next-yak/blob/main/CLAUDE.md

Starts the Vite example application. This command allows testing the integration with Vite projects.

```bash
pnpm example:vite
```

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

### Run Example App

Source: https://github.com/digitecgalaxus/next-yak/blob/main/CONTRIBUTION.md

Build the entire project and then start the example Next.js application. This demonstrates the features of next-yak.

```bash
pnpm build
pnpm build:swc
pnpm example
```

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

### Build and Preview Vite Example

Source: https://github.com/digitecgalaxus/next-yak/blob/main/examples/vite/README.md

Build the Vite example for production and start a local preview server. This is useful for testing the production build.

```bash
pnpm --filter vite-yak-example build
pnpm --filter vite-yak-example preview
```

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

### Install and Build Dependencies

Source: https://github.com/digitecgalaxus/next-yak/blob/main/examples/vite/README.md

Install project dependencies and build the shared packages before running the Vite example. Ensure you are in the project root.

```bash
pnpm install
pnpm --filter yak-swc build
pnpm --filter next-yak build
```

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

### Install storybook-addon-yak

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/storybook.mdx

Install the addon using your preferred package manager.

```bash
npm i -D storybook-addon-yak
```

```bash
pnpm i -D storybook-addon-yak
```

```bash
yarn add -D storybook-addon-yak
```

```bash
bun add -D storybook-addon-yak
```

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

### Install Storybook Addon

Source: https://github.com/digitecgalaxus/next-yak/blob/main/README.md

Install the storybook-addon-yak for Storybook integration.

```bash
npm i -D storybook-addon-yak
```

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

### Run Next.js example

Source: https://github.com/digitecgalaxus/next-yak/blob/main/CLAUDE.md

Launches the Next.js example application. Ensure the project is built first using `pnpm build && pnpm build:swc` before running this command.

```bash
pnpm example
```

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

### Install Dependencies

Source: https://github.com/digitecgalaxus/next-yak/blob/main/CONTRIBUTION.md

Install all project dependencies, including peer dependencies, to resolve 'Missing dependencies' issues.

```bash
pnpm install
```

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

### Run documentation site

Source: https://github.com/digitecgalaxus/next-yak/blob/main/CLAUDE.md

Starts the documentation site locally. This is useful for previewing documentation changes.

```bash
pnpm docs
```

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

### Install Next-Yak with bun

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/getting-started.mdx

Install the latest version of next-yak for Next.js or Vite, or a specific version for older Next.js releases.

```bash
# For next.js >= 16.1.0 or vite
bun i next-yak@latest

# For other next.js versions use a specific version
bun i next-yak@2
```

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

### Install next-yak

Source: https://github.com/digitecgalaxus/next-yak/blob/main/README.md

Install the next-yak package using npm.

```bash
npm install next-yak
```

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

### Install eslint-plugin-yak

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/eslint-plugin.mdx

Install the plugin using npm, pnpm, yarn, or bun.

```bash
npm install -D eslint-plugin-yak
```

```bash
pnpm i -D eslint-plugin-yak
```

```bash
yarn i -D eslint-plugin-yak
```

```bash
bun i -D eslint-plugin-yak
```

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

### Clone and Install Dependencies

Source: https://github.com/digitecgalaxus/next-yak/blob/main/CONTRIBUTION.md

Clone the next-yak repository and install project dependencies using pnpm. These commands are run from your terminal.

```bash
git clone https://github.com/DigitecGalaxus/next-yak.git
cd next-yak
pnpm install
```

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

### Install next-yak

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/vite.mdx

Install the next-yak package using your preferred package manager.

```bash
npm i next-yak
# or
pnpm i next-yak
# or
yarn add next-yak
# or
bun add next-yak
```

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

### Install yak-swc with npm

Source: https://github.com/digitecgalaxus/next-yak/blob/main/packages/yak-swc/README.md

Install the yak-swc plugin using npm. Ensure the installed version is compatible with your project's @swc/core version.

```bash
npm install yak-swc
```

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

### Install yak-swc with yarn

Source: https://github.com/digitecgalaxus/next-yak/blob/main/packages/yak-swc/README.md

Install the yak-swc plugin using yarn. Ensure the installed version is compatible with your project's @swc/core version.

```bash
yarn add yak-swc
```

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

### Install Next-Yak with npm

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/getting-started.mdx

Install the latest version of next-yak for Next.js or Vite, or a specific version for older Next.js releases.

```bash
# For next.js >= 16.1.0 or vite
npm i next-yak@latest

# For other next.js versions use a specific version

npm i next-yak@2
```

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

### Run Vite Development Server

Source: https://github.com/digitecgalaxus/next-yak/blob/main/examples/vite/README.md

Start the Vite development server for the vite-yak-example. Access the application via the provided URL.

```bash
pnpm --filter vite-yak-example dev
```

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

### Install Next-Yak with pnpm

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/getting-started.mdx

Install the latest version of next-yak for Next.js or Vite, or a specific version for older Next.js releases.

```bash
# For Next.js >= 16.1.0 or vite
pnpm i next-yak@latest

# For other next.js versions use a specific version
pnpm i next-yak@2
```

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

### Install storybook-addon-yak

Source: https://github.com/digitecgalaxus/next-yak/blob/main/packages/storybook-addon-yak/README.md

Install the addon using npm. This command adds the package as a development dependency.

```bash
npm install --save-dev storybook-addon-yak
```

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

### Install Next-Yak with yarn

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/getting-started.mdx

Install the latest version of next-yak for Next.js or Vite, or a specific version for older Next.js releases.

```bash
# For next.js >= 16.1.0 or vite
yarn i next-yak@latest

# For other next.js versions use a specific version

yarn i next-yak@2
```

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

### Run Development Server (Webpack)

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/README.md

Use these commands to start the development server with Webpack. Choose the command corresponding to your package manager (npm, pnpm, or yarn).

```bash
# With webpack
npm run dev
# or
pnpm dev
# or
yarn dev
```

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

### Transform styled components output

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/features.mdx

Example showing the input styled component syntax and its corresponding transformed output.

```javascript
const Header = styled.nav`
  ${({$variant}) => $variant === "primary"
    ? atoms("mx-auto flex max-w-7xl items-center justify-between p-6 lg:px-8")
    : atoms("bg-white hover:bg-gray-100 text-gray-800 font-semibold py-2 px-4 border border-gray-400 rounded shadow")
  }
`
```

```javascript
const Header = styled.nav('.Header',
  ({$variant}) => $variant === "primary"
    ? atoms("mx-auto flex max-w-7xl items-center justify-between p-6 lg:px-8")
    : atoms("bg-white hover:bg-gray-100 text-gray-800 font-semibold py-2 px-4 border border-gray-400 rounded shadow"))
```

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

### Enable Debug Logging in Example App

Source: https://github.com/digitecgalaxus/next-yak/blob/main/CONTRIBUTION.md

Configure the Next.js example app to enable debug logging for the next-yak plugin. Modify the `next.config.mjs` file to include the `experiments.debug` option.

```javascript
export default withYak({
  experiments: {
    debug: true, // or { filter: 'component.tsx.css$' }
  },
});
```

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

### Run Development Server (Turbopack)

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/README.md

Use these commands to start the development server with Turbopack. Choose the command corresponding to your package manager (npm, pnpm, or yarn).

```bash
# With turbopack
npm run dev:turbo
# or
pnpm run dev:turbo
# or
yarn dev:turbo
```

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

### Transform dynamic CSS to build-time variables

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/features.mdx

Examples showing the input code and the resulting JavaScript and CSS transformations for mixins.

```jsx
const mixin = css`
  color: ${(props) => props.$green ? 'green' : 'blue'};
`;

const MyComp = styled.div`  background-color: yellow;
  ${mixin}`;
```

```jsx
const mixin = css('mixin_0', {
  style: {
    "--yakVar1": props => props.$green ? 'green' : 'blue'
  },
});

const MyComp = styled.div('MyComp', mixin);
```

```css
.mixin_0 {
  color: var(--yakVar1);
}

.MyComp {
background-color: yellow;
}
```

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

### Basic Next-Yak Component Example

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/getting-started.mdx

Demonstrates how to use the `styled` utility from next-yak to create a styled div component. This is similar to styled-components syntax.

```jsx
import { styled } from "next-yak";

const StyledDiv = styled.div`
  color: #333;
  padding: 16px;
  background-color: #f0f0f0;
`;

export default function HomePage() {
  return <StyledDiv>Hello, next-yak!</StyledDiv>;
}
```

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

### Install ESLint Plugin Yak

Source: https://github.com/digitecgalaxus/next-yak/blob/main/packages/eslint-plugin-yak/README.md

Install the plugin as a development dependency using npm.

```bash
npm install --save-dev eslint-plugin-yak
```

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

### Transform globalStyle input to output

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/features.mdx

Example showing the transformation of a globalStyle block into JavaScript and CSS outputs.

```jsx
globalStyle`
  body {
    margin: 0;
  }
`;
```

```jsx
globalStyle();
```

```css
body {
  margin: 0;
}
```

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

### Transform animation input to output

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/features.mdx

Example showing the transformation of keyframes and styled components into their respective JavaScript and CSS outputs.

```jsx
const fadeIn = keyframes`
  0% {
    opacity: 0;
  }
  100% {
    opacity: 1;
  }
`

const FadeInButton = styled.button`  animation: 1s ${fadeIn} ease-out;`
```

```jsx
const fadeIn = keyframes('fadeIn')

const FadeInButton = styled.button('.FadeInButton', {
  style: { "--yakVar1": fadeIn }
})
```

```css
@keyframes fadeIn {
  0% {
    opacity: 0;
  }
  100% {
    opacity: 1;
  }
}

.FadeInButton {
animation: 1s var(--yakVar1) ease-out;
}
```

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

### Theme Context Setup in preview.tsx

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/storybook.mdx

Wrap your stories with YakThemeProvider in preview.tsx to manage theme context.

```tsx
import type { Preview } from "@storybook/react";
import { YakThemeProvider } from "next-yak";
import { getYakThemeContext } from "next-yak/context/baseContext";

const preview: Preview = {
  decorators: [
    (Story) => (
      <YakThemeProvider theme={getYakThemeContext()}>
        <Story />
      </YakThemeProvider>
    ),
  ],
};

export default preview;
```

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

### Build Project

Source: https://github.com/digitecgalaxus/next-yak/blob/main/CONTRIBUTION.md

Build all packages in the monorepo, including the main TypeScript/JavaScript package and the Rust SWC plugin. This is a prerequisite for running examples or tests.

```bash
pnpm run build
pnpm run build:swc
```

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

### Basic Usage in Next.js

Source: https://github.com/digitecgalaxus/next-yak/blob/main/README.md

Start styling components in your Next.js application using the styled API.

```jsx
import { styled } from "next-yak";

const StyledDiv = styled.div`
  color: #333;
  padding: 16px;
  background-color: #f0f0f0;
`;

function HomePage() {
  return <StyledDiv>Hello, next-yak!</StyledDiv>;
}

export default HomePage;
```

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

### React Component Theme Provider Setup

Source: https://github.com/digitecgalaxus/next-yak/blob/main/packages/next-yak/runtime/context/README.md

Sets up the YakThemeProvider with a specific theme value for standard React Components.

```tsx
// _app.tsx
import { YakThemeProvider } from "next-yak/context";

const theme = {
    colors: {
        primary: "red",
        secondary: "blue",
    },
};

declare module "next-yak/context" {
    export interface YakTheme extends typeof theme { } 
}

export function App({ children }) {
    return (
        <YakThemeProvider value={theme}>
            {children}
        </YakThemeProvider>
    );
}
```

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

### Transform automatic CSS variables

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/features.mdx

Examples showing the input code and the resulting JavaScript and CSS transformations for automatic variables.

```jsx
const Box = styled.div`
  font-size: ${props => props.$variant === "primary" ? "2rem" : "1rem" };
  color: ${props => props.$color};
  display: flex;
`
```

```jsx
const Box = styled.div('.Box', {
  style: {
    '--var1': props => props.$variant === "primary" ? "2rem" : "1rem",
    '--var2': props => props.$color
  }
})
```

```css
.Box {
  font-size: var(--var1);
  color: var(--var2);
  display: flex;
}
```

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

### Build the main next-yak TypeScript package

Source: https://github.com/digitecgalaxus/next-yak/blob/main/CLAUDE.md

Use this command to build the primary TypeScript package for next-yak. Ensure all dependencies are installed before running.

```bash
pnpm build
```

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

### Example Test Case Component

Source: https://github.com/digitecgalaxus/next-yak/blob/main/e2e/README.md

A basic React component using next-yak's styled utility to create a styled div.

```tsx
// cases/my-case/index.tsx
import { styled } from "next-yak";
const Box = styled.div`
  background: blue;
`;
export default function App() {
  return <Box data-testid="box">Test</Box>;
}
```

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

### React Server Component Theme Context Setup

Source: https://github.com/digitecgalaxus/next-yak/blob/main/packages/next-yak/runtime/context/README.md

Defines an asynchronous function to retrieve theme context for React Server Components and declares the YakTheme interface.

```tsx
// yak.context.tsx
export async function getYakThemeContext() {
  return {
    colors: {
      primary: "red",
      secondary: "blue",
    },
  };
}

declare module "next-yak/context" {
  export interface YakTheme extends Awaited<ReturnType<typeof getYakThemeContext>> {}
}
```

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

### Improve runtime performance with CSS literals

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/eslint-plugin.mdx

Demonstrates how to improve runtime performance by using CSS literals instead of inline functions or conditional logic for dynamic styles. Examples with inline functions and conditional logic are commented out.

```tsx
styled.button`
//[!code --]
  color: ${() => color};
//[!code ++]
  color: ${({$color}) => $color};
// or if the value is defined outside the component: // [!code ++]
//[!code ++]
  color: ${color};
`;
```

```tsx
styled.button`
  color: ${() => {
    if (variant === 'primary') {
      return primary; // [!code --]
      return css` // [!code ++]
        color: ${({$primary}) => $primary}; // [!code ++]
      `; // [!code ++]
      // or if the value is defined outside the component: // [!code ++]
      return css` // [!code ++]
        color: ${primary}; // [!code ++]
      `; // [!code ++]
    } else {
      return secondary; // [!code --]
      return css` // [!code ++]
        color: ${({$secondary}) => $secondary}; // [!code ++]
      `; // [!code ++]
      // or if the value is defined outside the component: // [!code ++]
      return css` // [!code ++]
        color: ${secondary}; // [!code ++]
      `; // [!code ++]
    }
  }};
`;
```

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

### Building and Running Benchmark Harness

Source: https://github.com/digitecgalaxus/next-yak/blob/main/benchmarks/README.md

Build the project and run the benchmark harness locally to generate an HTML results table.

```bash
# Build + run the benchmark harness locally and print an HTML results table:
pnpm bench
```

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

### Recommended ESLint Configuration

Source: https://github.com/digitecgalaxus/next-yak/blob/main/packages/eslint-plugin-yak/README.md

Import the plugin and apply the recommended configuration for ESLint.

```javascript
import yakPlugin from "eslint-plugin-yak";
import { defineConfig } from "eslint/config";

export default defineConfig([yakPlugin.configs.recommended]);
```

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

### Mixin vs Selector Ambiguity Example

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/eslint-plugin.mdx

This example explains why a semicolon is needed after a mixin to avoid ambiguity between mixins and nested selectors in next-yak's static analysis.

```tsx
// This works correctly - mixin properly terminated with semicolon
styled.div`
  ${skeleton};
  div {
    color: blue;
  }
`

// This causes ambiguity - is it a mixin or part of the selector?
styled.div`
  ${skeleton}
  div {
    color: blue;
  }
`
```

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

### Build Time Constants for Media Queries

Source: https://github.com/digitecgalaxus/next-yak/blob/main/README.md

Illustrates using build-time constants for responsive styles, avoiding inline style attributes for media queries. Constants like 'breakpoints' and 'spacings' are imported from a '.yak' file.

```jsx
import { styled } from "next-yak";
import { breakpoints, spacings } from "./constants.yak";

const Container = styled.div`
  padding: ${spacings.md};
  ${breakpoints.md} {
    padding: ${spacings.lg};
  }
`;

```

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

### Styled Component Theme Usage

Source: https://github.com/digitecgalaxus/next-yak/blob/main/packages/next-yak/runtime/context/README.md

Example of using theme colors within a styled-component.

```tsx
const Headline = styled.h1`
  color: ${(props) => props.theme.colors.primary};
`;
```

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

### Colocation with JavaScript

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/why-next-yak.mdx

Demonstrates colocation of styles and component logic in JavaScript using styled-jsx.

```javascript
import { styled } from 'next-yak';

const MyParagraph = styled.p`
  color: ${({$variant}) => $variant === 'primary' ? "red" : "blue"}
`;

const MyOtherComponent = styled.p``;

export const MyComponent = (props) => {
  if(props.$variant) {
    return (<MyParagraph $variant={props.$variant}>{props.children}</MyParagraph>);
  }

  return (<MyOtherComponent>{props.children}</MyOtherComponent>);
}

```

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

### evaluator.invalidateAll

Source: https://github.com/digitecgalaxus/next-yak/blob/main/packages/next-yak/isolated-source-eval/README.md

Clears the entire result cache and swaps workers, ensuring all subsequent evaluations start with a clean state.

```APIDOC
## evaluator.invalidateAll()

### Description
Clears the entire result cache and swaps workers.

### Method
N/A (Function Call)

### Parameters
None

### Request Example
```ts
evaluator.invalidateAll();
```

### Response
N/A (This is a command, not a query)
```

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

### Using Build-time Tokens in Components

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/vite.mdx

Demonstrates how to import and use the build-time generated spacing and color tokens within a styled component.

```tsx
/** @jsxImportSource next-yak */
import { styled } from "next-yak";
import { spacing, colors } from "./theme/tokens.yak";

const Card = styled.div`
  padding: ${spacing.s3};
  background-color: ${colors[4]};
  border-radius: ${spacing.s2};
`;
```

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

### Build all packages

Source: https://github.com/digitecgalaxus/next-yak/blob/main/CLAUDE.md

Executes both the TypeScript package build and the Rust SWC plugin build. This command is required before running the project for the first time or after significant changes.

```bash
pnpm build && pnpm build:swc
```

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

### Example Playwright Test

Source: https://github.com/digitecgalaxus/next-yak/blob/main/e2e/README.md

A Playwright test that uses the withTestEnv helper to verify the CSS background color of a styled component.

```typescript
// cases/my-case/index.test.ts
import { test, expect } from "@playwright/test";
import { withTestEnv } from "next-yak-e2e";

test(
  "applies background",
  withTestEnv("my-case", async (fsTmp, page) => {
    await page.goto(fsTmp.url);
    await expect(page.getByTestId("box")).toHaveCSS("background-color", "rgb(0, 0, 255)");
  }),
);

```

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

### Run all tests

Source: https://github.com/digitecgalaxus/next-yak/blob/main/CLAUDE.md

Executes the entire test suite for the project. This command automatically performs a build before running tests.

```bash
pnpm test
```

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

### Running Benchmarks in Dev Mode

Source: https://github.com/digitecgalaxus/next-yak/blob/main/benchmarks/README.md

Use these commands to run benchmarks in development mode. `pnpm dev` automatically runs generators first to ensure fresh benchmark sources.

```bash
# Browse benchmarks in dev mode (also runs all generators first):
pnpm dev          # http://localhost:3000
pnpm dev:turbo    # same, but Turbopack instead of Webpack
```

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

### Nesting selector missing warning

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/eslint-plugin.mdx

This example shows a code snippet that would trigger an ESLint warning for a missing nesting selector.

```ts
const myDiv = styled.div`
    > div {}
`;
// ^ eslint: Nesting selector missing. Did you forget the &?
```

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

### Create Changelog Entry

Source: https://github.com/digitecgalaxus/next-yak/blob/main/CONTRIBUTION.md

Generate a changelog entry for your changes. Use the `--empty` flag if there are no changes to the public API.

```bash
pnpm changeset
```

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

### Create a styled component with next-yak

Source: https://github.com/digitecgalaxus/next-yak/blob/main/packages/next-yak/README.md

Define a styled component using the styled API provided by next-yak. This example creates a styled button.

```jsx
import { styled } from "next-yak";

const Button = styled.button`
  background: #bf4f74;
  color: white;
  padding: 0.5rem 1rem;
  border-radius: 4px;
`;
```

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

### Build the Rust SWC plugin

Source: https://github.com/digitecgalaxus/next-yak/blob/main/CLAUDE.md

This command compiles the Rust SWC plugin, generating the WebAssembly (WASM) binary. This is a necessary step for integrating the plugin.

```bash
pnpm build:swc
```

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

### Build and Test yak-swc Rust Plugin

Source: https://github.com/digitecgalaxus/next-yak/blob/main/CONTRIBUTION.md

Commands to build, test, and update snapshots for the yak-swc Rust plugin. It's recommended to open your IDE in the `./packages/yak-swc` directory for correct Rust toolchain operation.

```bash
pnpm build
pnpm test
pnpm test:snapshots
```

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

### Correctly terminated mixin with semicolon

Source: https://github.com/digitecgalaxus/next-yak/blob/main/packages/eslint-plugin-yak/docs/rules/enforce-semicolon.md

This example demonstrates the correct usage where a mixin is properly terminated with a semicolon, allowing for clear distinction from nested selectors.

```tsx
styled.div`
  ${skeleton};
  div {
    color: blue;
  }
`
```

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

### Configure CSS prop support

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/migration-from-styled-components.mdx

Enable the css prop by updating tsconfig.json or using a file-level pragma.

```json
{
  "compilerOptions": {
    "jsxImportSource": "next-yak" // [!code ++]
  }
}
```

```tsx
/** @jsxImportSource next-yak */ // [!code ++]
```

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

### Get Dependents of a File

Source: https://github.com/digitecgalaxus/next-yak/blob/main/packages/next-yak/isolated-source-eval/README.md

Retrieves an array of entry point paths that would be affected if the specified file were invalidated. Useful for debugging dependency tracking.

```typescript
evaluator.getDependentsOf("/project/src/tokens.ts");
// ["/project/src/theme.ts", "/project/src/dark-theme.ts"]
```

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

### Ambiguous mixin without semicolon

Source: https://github.com/digitecgalaxus/next-yak/blob/main/packages/eslint-plugin-yak/docs/rules/enforce-semicolon.md

This example shows an ambiguous case where a mixin is not terminated with a semicolon, potentially causing confusion with nested selectors during static analysis.

```tsx
styled.div`
  ${skeleton}
  div {
    color: blue;
  }
`
```

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

### Package.json Context Configuration

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/how-does-it-work.mdx

Defines the import paths for the server and client versions of the context module in `package.json`.

```json
./context": {
	"react-server": {
		"import": "./dist/context/index.server.js",
		"require": "./dist/context/index.server.cjs"
	},
	"default": {
		"import": "./dist/context/index.js",
		"require": "./dist/context/index.cjs"
	}
}
```

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

### Build and Test next-yak TypeScript/JavaScript

Source: https://github.com/digitecgalaxus/next-yak/blob/main/CONTRIBUTION.md

Commands to build, test, and update snapshots for the next-yak TypeScript/JavaScript package. Run these from the project root or the package directory.

```bash
pnpm build
pnpm test
pnpm test:watch
pnpm test:snapshots
```

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

### Regenerating Benchmark Sources

Source: https://github.com/digitecgalaxus/next-yak/blob/main/benchmarks/README.md

Run this command to regenerate the benchmark source files. This process is parallelized.

```bash
# Regenerate just the source files (parallelized):
pnpm generate
```

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

### Run tests in watch mode

Source: https://github.com/digitecgalaxus/next-yak/blob/main/CLAUDE.md

Starts the test runner in watch mode, automatically re-running tests when file changes are detected. Useful for continuous testing during development.

```bash
pnpm test:watch
```

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

### Colocation with TypeScript

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/why-next-yak.mdx

Demonstrates colocation of styles and component logic in TypeScript using styled-jsx.

```typescript
import { FC, ReactNode } from 'react';
import { styled } from 'next-yak';

const MyParagraph = styled.p<{ $variant?: 'primary' | 'secondary' }>`
  color: ${({$variant}) => $variant === 'primary' ? "red" : "blue"}
`;

const MyOtherComponent = styled.p``;

export const MyComponent: FC<{ $variant?: 'primary' | 'secondary'; children: ReactNode }> = (props) => {
  if(props.$variant) {
    return (<MyParagraph $variant={props.$variant}>{props.children}</MyParagraph>);
  }

return (<MyOtherComponent>{props.children}</MyOtherComponent>);
}

```

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

### Configure dynamic theme context

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/features.mdx

Create a yak.context.ts file to define the theme structure and provide context values, using module augmentation to type the theme.

```typescript
// @noErrors
const getMyBrandName: () => string | undefined = () => "test";
const isNewDesign: () => boolean | undefined = () => true;

// ---cut---
export async function getYakThemeContext() {
  return {
    brandName: getMyBrandName() ?? "myDefaultBrand",
    featureFlags: {
      newDesign: isNewDesign() ?? false,
    },
  };
}

declare module "next-yak" {
  export interface YakTheme extends Awaited<ReturnType<typeof getYakThemeContext>> {}
}
```

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

### Automatic cleanup with await using

Source: https://github.com/digitecgalaxus/next-yak/blob/main/packages/next-yak/isolated-source-eval/README.md

Demonstrates using `await using` for automatic cleanup of the evaluator instance, ensuring resources are released.

```typescript
await using evaluator = await createEvaluator();
```

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

### Custom ESLint Configuration with Rules

Source: https://github.com/digitecgalaxus/next-yak/blob/main/packages/eslint-plugin-yak/README.md

Customize ESLint settings by importing the plugin and overriding specific rules.

```javascript
import yakPlugin from "eslint-plugin-yak";
import { defineConfig } from "eslint/config";

export default defineConfig({
  plugins: {
    yak: yakPlugin,
  },
  rules: {
    "eslint-plugin-yak/css-nesting-operator": "error",
    "eslint-plugin-yak/enforce-semicolon": "warn",
    "eslint-plugin-yak/style-conditions": "off",
  },
});
```

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

### Capturing HTML Benchmark Table to File

Source: https://github.com/digitecgalaxus/next-yak/blob/main/benchmarks/README.md

Capture the HTML benchmark table to a file. This is how the CI workflow collects results for posting as a PR comment.

```bash
BENCH_OUTPUT_FILE=./bench-table.html pnpm bench
```

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

### Running E2E Dev Tests

Source: https://github.com/digitecgalaxus/next-yak/blob/main/e2e/README.md

Execute end-to-end tests against development servers for all bundlers and cases, or filter by specific bundler and case combinations.

```bash
pnpm --filter next-yak-e2e test
pnpm --filter next-yak-e2e test next-app-webpack
pnpm --filter next-yak-e2e test vite yak-file-mixin
```

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

### Enable JSX Runtime with css Prop

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/vite.mdx

Configure the JSX import source to 'next-yak' for using the css prop or compile-time JSX transforms.

```typescript
/** @jsxImportSource next-yak */
import { styled, css } from "next-yak";

const Title = styled.h1`
  ${({ $primary }: { $primary?: boolean }) =>
    $primary &&
    css`
      color: teal;
    `}
`;
```

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

### Configure next-yak in Vite

Source: https://github.com/digitecgalaxus/next-yak/blob/main/README.md

Set up next-yak for Vite projects by adding the viteYak plugin to vite.config.ts.

```javascript
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";
import { viteYak } from "next-yak/vite";

export default defineConfig({
  plugins: [viteYak(), react()],
});
```

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

### Composability of Styled Components

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/why-next-yak.mdx

Demonstrates building complex components by composing simpler styled elements in TypeScript.

```typescript
import { styled } from "next-yak";

const Input = styled.input``;
const Label = styled.label``;
const FormElement = styled.div`
  :has(${Input}:checked) {
    color: red;
  }
`;

```

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

### Run Rust fixture tests

Source: https://github.com/digitecgalaxus/next-yak/blob/main/CLAUDE.md

Executes all Rust tests, including fixture-based snapshot tests. This command is run from the `packages/yak-swc/yak_swc` directory.

```bash
cargo test
```

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

### Storybook Configuration (Vite)

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/storybook.mdx

Add the addon to your Storybook's main.ts configuration for Vite projects.

```typescript
import type { StorybookConfig } from "@storybook/react-vite";

const config: StorybookConfig = {
  stories: ["../src/**/*.stories.@(js|jsx|ts|tsx)"],
  addons: ["@storybook/addon-docs", "storybook-addon-yak"],
  framework: {
    name: "@storybook/react-vite",
    options: {},
  },
};

export default config;
```

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

### viteYak Plugin Options

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/vite.mdx

Configure the viteYak plugin with options such as minify, prefix, contextPath, basePath, and experiments.

```typescript
viteYak({
  // compact class names in production
  minify: process.env.NODE_ENV === "production",
  // optional prefix for generated identifiers
  prefix: "my-app",
  // optional custom path to your yak context file
  // (relative to the project root)
  contextPath: "yak.context",
  // base path for CSS virtual module resolution (default: Vite's root)
  // useful in monorepo setups where source files live outside the Vite root
  // relative paths are resolved from Vite's project root
  basePath: "../..",
  experiments: {
    // enable logging of transformed TS/CSS
    debug: false,
  },
});
```

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

### Resume CSS Parsing from Previous State

Source: https://github.com/digitecgalaxus/next-yak/blob/main/packages/yak-swc/css_in_js_parser/README.md

Demonstrates how to resume CSS parsing by providing a previous parser state. This allows for incremental parsing of CSS chunks.

```rust
let (state1, declarations1) = parse_css(chunk1, None);
let (_, declarations2) = parse_css(chunk2, Some(state1));
let combined_declarations: Vec<_> = declarations1.into_iter().chain(declarations2.into_iter()).collect();
let merged_css = to_css(&combined_declarations);
```

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

### Transform dynamic styles to CSS variables

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/features.mdx

Demonstrates how dynamic styles are converted into CSS variables and class-based conditional logic.

```jsx
const Paragraph = styled.p`
  background: ${props => props.$primary ? "#BF4F74" : "white"};
  ${props => props.$primary ?
    css`
      color: white;
    ` :
    css`
      color: #BF4F74;
    `}
  font-size: 2rem;
  font-weight: bold;
`;
```

```jsx
const Paragraph = styled.p(
  '.Paragraph',
  props => props.$primary ? css('.propsprimary_0') : css('.not_propsprimary_1'),
  {
    style: { '--var1': props => props.$primary ? "#BF4F74" : "white" }
  }
);
```

```css
.Paragraph {
  background: var(--var1);

&:where(.propsprimary_0) {
color: white;
}

&:where(.not_propsprimary_1) {
color: #BF4F74;
}

font-size: 2rem;
font-weight: bold;
}
```

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

### Create an evaluator instance

Source: https://github.com/digitecgalaxus/next-yak/blob/main/packages/next-yak/isolated-source-eval/README.md

Creates and initializes an evaluator instance, booting both primary and shadow workers. Waits until both workers are ready for evaluation.

```typescript
const evaluator = await createEvaluator();
```

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

### Wrap App with YakThemeProvider

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/vite.mdx

Use YakThemeProvider to provide the theme context to your application and import the theme from next-yak/context/baseContext.

```typescript
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import App from "./App";
import { YakThemeProvider } from "next-yak";
import { getYakThemeContext } from "next-yak/context/baseContext";
import "./globals.css";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <YakThemeProvider theme={getYakThemeContext()}>
      <App />
    </YakThemeProvider>
  </StrictMode>,
);
```

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

### to_css

Source: https://github.com/digitecgalaxus/next-yak/blob/main/packages/yak-swc/css_in_js_parser/README.md

Converts a slice of parsed CSS declarations back into a formatted CSS string.

```APIDOC
## to_css

### Description
Converts a slice of `Declaration` objects, typically obtained from `parse_css`, back into a prettified CSS string.

### Method
`to_css(declarations: &[Declaration]) -> String`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **declarations** (`&[Declaration]`) - A slice of `Declaration` objects to convert to a CSS string.

### Returns
- **String**: A formatted CSS string representing the provided declarations.
```

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

### Running E2E Build Tests

Source: https://github.com/digitecgalaxus/next-yak/blob/main/e2e/README.md

Execute end-to-end tests against production builds, excluding HMR cases, for all bundlers or specific ones.

```bash
pnpm --filter next-yak-e2e test:build
pnpm --filter next-yak-e2e test:build vite
```

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

### Define Build-Time Constants in .yak.ts

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/features.mdx

Use .yak.ts files to compute values at build time using standard JavaScript logic, which are then inlined into static CSS.

```tsx
export const spacing = {
  xs: "4px",
  sm: "8px",
  md: "16px",
  lg: "32px",
};

export const spacingTokens = Object.entries(spacing).reduce(
  (acc, [key, value]) => ({
    ...acc,
    [key]: `padding: ${value}; margin: ${value};`,
  }),
  {} as Record<string, string>,
);
```

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

### Define static styles with styled-components API

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/features.mdx

Use the styled API to define components with static CSS that is extracted during build time.

```jsx
import { styled } from "next-yak";

const Headline = styled.h1`
  font-size: 2rem;
  font-weight: bold;
  color: rgba(253, 29, 29, 1);
`;

const Component = () => {
  return <Headline>Hello there!</Headline>;
};
```

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

### Build yak-swc WASM package

Source: https://github.com/digitecgalaxus/next-yak/blob/main/CLAUDE.md

Builds only the WASM binary for the yak-swc package. This command is run from within the `packages/yak-swc` directory.

```bash
cd packages/yak-swc && pnpm build:yak
```

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

### Define and use a static CSS mixin

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/features.mdx

Create a reusable CSS block using the css utility and inject it into a styled component.

```jsx
import { css, styled } from 'next-yak';

const mixin = css`
  color: green;
`;

const MyComp = styled.div`
  background-color: yellow;
  ${mixin}
`;
```

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

### Implement async theme context for Next.js 15+

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/features.mdx

Await asynchronous server-side APIs like cookies or headers within the getYakThemeContext function.

```typescript
import { cookies } from "next/headers";

export async function getYakThemeContext() {
  const cookieStore = await cookies();
  return {
    highContrast: cookieStore.get("highContrast")?.value === "true",
  };
}

declare module "next-yak" {
  export interface YakTheme extends Awaited<ReturnType<typeof getYakThemeContext>> {}
}
```

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

### Enable Debugging for All Files

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/faq.mdx

To enable style debugging for all files, set the `debug` option to `true` within the `experiments` object in your `next.config.ts` file. This helps in inspecting the transformed output of your components.

```typescript
export default withYak({
  experiments: {
    // Enable for all files
    debug: true,

    // Or filter by regex pattern
    debug: { pattern: "myPage" },

    // Or filter by output type only
    debug: { types: ["css"] },

    // Or combine pattern + types
    debug: { pattern: "Button", types: ["css", "css-resolved"] },

},
}, nextConfig);
```

```javascript
module.exports = withYak({
  experiments: {
    // Enable for all files
    debug: true,

    // Or filter by regex pattern
    debug: { pattern: "myPage" },

    // Or filter by output type only
    debug: { types: ["css"] },

    // Or combine pattern + types
    debug: { pattern: "Button", types: ["css", "css-resolved"] },
  },
}, nextConfig);
```

```javascript
export default withYak({
  experiments: {
    // Enable for all files
    debug: true,

    // Or filter by regex pattern
    debug: { pattern: "myPage" },

    // Or filter by output type only
    debug: { types: ["css"] },

    // Or combine pattern + types
    debug: { pattern: "Button", types: ["css", "css-resolved"] },

},
}, nextConfig);
```

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

### Configure Vite with next-yak

Source: https://github.com/digitecgalaxus/next-yak/blob/main/packages/next-yak/README.md

Add the viteYak plugin to your Vite configuration to enable next-yak support.

```javascript
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";
import { viteYak } from "next-yak/vite";

export default defineConfig({
  plugins: [viteYak(), react()],
});
```

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

### Combine utility classes with the css prop

Source: https://github.com/digitecgalaxus/next-yak/blob/main/docs/content/docs/features.mdx

Integrate the atoms function with the css prop for a utility-first styling approach.

```jsx
import { css } from "next-yak";

const Component = (props) => {
  return <div css={atoms("bg-red-500", props.primary && "bg-blue-500")}>Hello there!</div>;
};
```

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

### Add Rust WebAssembly Target

Source: https://github.com/digitecgalaxus/next-yak/blob/main/CONTRIBUTION.md

Add the Rust WebAssembly target required for the project. Execute this command in your terminal.

```bash
rustup target add wasm32-wasip1
```