For the complete documentation index, see llms.txt. Markdown variants are available by appending .md to any URL or sending an Accept: text/markdown header. An agent skill is available at /.well-known/agent-skills/site-skill.md.
FrakmentFrakment

Gatsby

Install and configure Frakment for Gatsby.

Frakment works in any Gatsby 5+ project with React 19 and Tailwind v4. This guide covers both a new project via the CLI and an existing app.

Prerequisites

  • Gatsby 5 or newer
  • React 19
  • TypeScript
  • Tailwind CSS v4

Components target React 19 and Tailwind v4. For React 18, some components need forwardRef adjustments. For Tailwind v3, port the tokens from Theming manually.

Use the CLI

Scaffold a new Gatsby app with Frakment installed.

Create project

npm init gatsby
cd app

Install Tailwind v4

$ npm install tailwindcss@latest gatsby-plugin-postcss postcss

Add the plugin in gatsby-config.ts:

gatsby-config.ts
import type { GatsbyConfig } from "gatsby";
 
const config: GatsbyConfig = {
  plugins: ["gatsby-plugin-postcss"],
};
 
export default config;

Create src/styles/global.css:

src/styles/global.css
@import "tailwindcss";

Add components

$ npx frakment@latest init
npx frakment@latest add bubble

Use it

src/pages/index.tsx
import { Bubble, BubbleContent } from "@/components/ui/message";
 
export default function Index() {
  return (
    <Bubble>
      <BubbleContent>Hello, Frakment.</BubbleContent>
    </Bubble>
  );
}

Existing Project

Add Frakment to a Gatsby app you already created.

Install Tailwind v4

$ npm install tailwindcss@latest gatsby-plugin-postcss postcss

Register gatsby-plugin-postcss in gatsby-config.ts.

Run frakment init

$ npx frakment@latest init

Point to src/styles/global.css when prompted. The CLI injects the theme block.

Configure the import alias

In tsconfig.json:

tsconfig.json
{
  "compilerOptions": {
    "baseUrl": "src",
    "paths": {
      "@/*": ["./*"]
    }
  }
}

Add a component

$ npx frakment@latest add bubble

Project structure

package.json
gatsby-config.ts
tsconfig.json
index.tsx
global.css

Verify

ls src/components/ui/bubble.tsx

Then render it in a page. If it renders without errors, you are ready.

Troubleshooting

Gatsby does not ship Tailwind v4 out of the box. Make sure gatsby-plugin-postcss is registered in gatsby-config.ts and restart with gatsby develop --clear-cache.

Gatsby puts source in src/. Set "baseUrl": "src" and "@/*": ["./*"] in tsconfig.json.

Next