Use an existing theme

Commit or back up your theme first. From the theme folder, check that package.json declares engines.ghost, then run:

npx ghostcn@1.4.0 init
npx ghostcn@1.4.0 list
npx ghostcn@1.4.0 add newsletter-form --skip-existing

init sets up components.json, design tokens, and the managed stylesheet block in default.hbs. If your theme uses a different layout, follow the CLI’s manual linking instructions. Partial aliases must stay under partials/; update the example calls to match your alias.

Tailwind v4Copy Anchor Link

Ghostcn doesn’t install Tailwind into an existing theme. Keep your build pipeline, import the generated semantic token mapping, and make sure the compiler scans your Handlebars files. For a source file at assets/css/source.css:

@import "tailwindcss";
@import "./ghostcn-tailwind.css";
@source "../../**/*.hbs";

Ghostcn defaults are in the Tailwind components layer, so ordinary utilities can override them. Unlayered host rules still outrank layered rules. Older Tailwind versions need their own semantic token mappings. Rebuild after adding utilities.

Vanilla CSSCopy Anchor Link

Component styles work without a utility compiler. Put overrides in a theme-owned stylesheet loaded after the managed Ghostcn styles, and keep your existing build command.

Check and packageCopy Anchor Link

npx ghostcn@1.4.0 doctor
# Run your existing build command first.
npx ghostcn@1.4.0 pack

doctor checks configuration, partials, built assets, stylesheet links, and Ghost hooks offline. pack bundles the built theme without running its build. Validate against your target Ghost version and test it in a running publication.

Before updating copied files, see Review component updates.