How macaron works

File resolution

The esbuild/vite plugin loads every typescript and javascript file and runs @macaron-css/babel plugin on it.

main.tsx
Copy

import { styled } from '@macaron-css/react';
const borderRadius = 6;
const Button = styled('button', {
base: {
borderRadius: borderRadius,
},
variants: {
color: {
neutral: { background: 'whitesmoke' },
brand: { background: 'blueviolet' },
accent: { background: 'slateblue' },
},
},
defaultVariants: {
color: 'accent',
},
});

Babel transform

The babel plugin looks for call expressions in your code and checks if the callee is a macarons API like styled or recipe etc.

main.tsx
Copy

import { styled } from '@macaron-css/react';
const borderRadius = 6;
const Button = styled('button', {
base: {
borderRadius: borderRadius,
},
variants: {
color: {
neutral: { background: 'whitesmoke' },
brand: { background: 'blueviolet' },
accent: { background: 'slateblue' },
},
},
defaultVariants: {
color: 'accent',
},
});

Finding references

It traverses the call expressions and finds all the referenced identifiers, gets all their declarations and repeats this cycle until no more are found.

main.tsx
Copy

import { styled } from '@macaron-css/react';
const borderRadius = 6;
const Button = styled('button', {
base: {
borderRadius: borderRadius,
},
variants: {
color: {
neutral: { background: 'whitesmoke' },
brand: { background: 'blueviolet' },
accent: { background: 'slateblue' },
},
},
defaultVariants: {
color: 'accent',
},
});

Extract styles

The babel plugin then extracts all these references and the styles into a seperate file and replaces the code with imports.

main.tsx
Copy

import { $macaron$$Button } from 'extracted_rxrhwu.css.ts';
import { $$styled } from '@macaron-css/react/runtime';
const Button = $$styled('button', $macaron$$Button);

extracted_rxrhwu.css.ts
Copy

import { recipe as _recipe } from "@macaron-css/core";
const borderRadius = 6;
export var _$macaron$$Button = _recipe({
base: {
borderRadius: borderRadius
},
variants: {
color: {
neutral: {
background: 'whitesmoke'
},
brand: {
background: 'blueviolet'
},
accent: {
background: 'slateblue'
}
}
},
defaultVariants: {
color: 'accent'
}
});
var _$macaron$$Button2 = _$macaron$$Button;

Evaluating to static css

The plugin then evaluates this file in isolation and generates static css with hashed classes, removing all the runtime styles.

main.tsx
extracted_rxrhwu.css.ts
Copy

import 'extracted_rxrhwu.vanilla.css';
import { createRuntimeFn } from '@macaron-css/core/create-runtime-fn';
export var $macaron$$Button = createRuntimeFn({
defaultClassName: 'extracted_rxrhwu__1g7h5za0',
variantClassNames: {
color: {
neutral: 'extracted_rxrhwu_color_neutral__1g7h5za1',
brand: 'extracted_rxrhwu_color_brand__1g7h5za2',
accent: 'extracted_rxrhwu_color_accent__1g7h5za3',
},
},
defaultVariants: {
color: 'accent',
},
});

extracted_rxrhwu.vanilla.css
Copy

.extracted_rxrhwu__1g7h5za0 {
border-radius: 6px;
}
.extracted_rxrhwu_color_neutral__1g7h5za1 {
background: whitesmoke;
}
.extracted_rxrhwu_color_brand__1g7h5za2 {
background: blueviolet;
}
.extracted_rxrhwu_color_accent__1g7h5za3 {
background: slateblue;
}

File resolution

The esbuild/vite plugin loads every typescript and javascript file and runs @macaron-css/babel plugin on it.

Babel transform

The babel plugin looks for call expressions in your code and checks if the callee is a macarons API like styled or recipe etc.

Finding references

It traverses the call expressions and finds all the referenced identifiers, gets all their declarations and repeats this cycle until no more are found.

Extract styles

The babel plugin then extracts all these references and the styles into a seperate file and replaces the code with imports.

Evaluating to static css

The plugin then evaluates this file in isolation and generates static css with hashed classes, removing all the runtime styles.

main.tsx
extracted_rxrhwu.css.ts
CopyExpandClose

import 'extracted_rxrhwu.vanilla.css';
import { createRuntimeFn } from '@macaron-css/core/create-runtime-fn';
export var $macaron$$Button = createRuntimeFn({
defaultClassName: 'extracted_rxrhwu__1g7h5za0',
variantClassNames: {
color: {
neutral: 'extracted_rxrhwu_color_neutral__1g7h5za1',
brand: 'extracted_rxrhwu_color_brand__1g7h5za2',
accent: 'extracted_rxrhwu_color_accent__1g7h5za3',
},
},
defaultVariants: {
color: 'accent',
},
});

extracted_rxrhwu.vanilla.css
Copy

.extracted_rxrhwu__1g7h5za0 {
border-radius: 6px;
}
.extracted_rxrhwu_color_neutral__1g7h5za1 {
background: whitesmoke;
}
.extracted_rxrhwu_color_brand__1g7h5za2 {
background: blueviolet;
}
.extracted_rxrhwu_color_accent__1g7h5za3 {
background: slateblue;
}