Installation: Gatsby

Core Idea

Gatsby setup is Tailwind CSS v3 only (docs explicitly recommend other frameworks for v4 on new projects). Requires manual webpack alias resolution via gatsby-node.ts, not just tsconfig.

Key Concepts

• npm init gatsby: scaffolds project; prompts for TypeScript and Tailwind CSS during setup.
• gatsby-node.ts webpack alias: Gatsby needs onCreateWebpackConfig to register the @/* alias at the bundler level, since tsconfig paths alone don't affect Gatsby's webpack resolution.

Code Examples

npm init gatsby
npx shadcn@latest init
npx shadcn@latest add button

import * as path from "path"

export const onCreateWebpackConfig = ({ actions }) => {
  actions.setWebpackConfig({
    resolve: {
      alias: {
        "@/components": path.resolve(__dirname, "src/components"),
        "@/lib/utils": path.resolve(__dirname, "src/lib/utils"),
      },
    },
  })
}

• O que demonstra: alias resolvido via webpack config do Gatsby, similar em espírito ao vite.config.ts alias do Vite.

Anti-patterns

• Skipping gatsby-node.ts: tsconfig.json paths alone won't make Gatsby's build resolve @/components/ui/* imports.
• Using this guide for a new project expecting Tailwind v4: it's explicitly v3-only; prefer Next.js/Vite/Astro for v4 support.

Key Takeaways

1. Gatsby is the only installation guide flagged as Tailwind v3-specific, a signal it's a legacy/secondary path.
2. Like Vite and (implicitly) other bundler-based setups, the alias needs both a tsconfig entry and a bundler-level config (here, webpack via gatsby-node.ts).

Connects To

• installation-vite: same "alias needs bundler config too" pattern.