Astro Installation

Purpose and Scope

This page explains how to install and configure shadcn/ui for Astro using the first-party documentation flow. The Astro installation guide is organized around a reader’s starting point: build a preset visually with shadcn/create, scaffold a new Astro project directly from the CLI, or configure an existing Astro application manually. In every path, the goal is not to consume a sealed component library. The project is prepared so the CLI can write component source into your app, and your Astro pages can import those files through the aliases chosen during setup.

Sources: apps/v4/content/docs/installation/astro.mdx, apps/v4/content/docs/installation/index.mdx, apps/v4/content/docs/installation/meta.json

Astro belongs to the shared installation section alongside Next.js, Vite, Laravel, React Router, Gatsby, TanStack-related pages, and manual setup. The installation overview recommends shadcn/create for new projects because it lets users preview choices and generate a framework-specific setup command. The Astro page specializes that shared model with the astro template, Astro page paths, and an example that imports a React-style UI component into an .astro page frontmatter block before rendering it inside a layout.

Sources: apps/v4/content/docs/installation/astro.mdx, apps/v4/content/docs/installation/gatsby.mdx, apps/v4/content/docs/installation/index.mdx, apps/v4/content/docs/installation/laravel.mdx, apps/v4/content/docs/installation/meta.json

Relevant Source Files

• apps/v4/content/docs/installation/astro.mdx: Defines the Astro-specific installation page, including shadcn/create, CLI scaffolding, monorepo handling, Card installation, and Astro import examples.
• apps/v4/content/docs/installation/gatsby.mdx: Provides neighboring installation context for a framework that uses manual TypeScript and bundler alias configuration, which helps explain why Astro’s template path is different from older or non-v4-first setup flows.
• apps/v4/content/docs/installation/index.mdx: Provides the shared installation overview, recommends shadcn/create for new projects, and lists astro as a supported CLI template.
• apps/v4/content/docs/installation/laravel.mdx: Shows a contrasting framework path where the CLI configures an app created outside shadcn, clarifying that Astro can be scaffolded directly with -t astro while Laravel starts from laravel new.
• apps/v4/content/docs/installation/manual.mdx: Documents the lower-level requirements behind existing-project setup: Tailwind CSS, dependencies, import aliases, package imports, global styles, and alignment with components.json.
• apps/v4/content/docs/installation/meta.json: Places astro in the installation navigation, confirming that Astro is part of the official installation guide family.

Core Primitives

The first primitive is shadcn/create, the visual setup surface recommended for new projects. In the Astro guide, the create link is scoped to template=astro, so the generated command targets an Astro project rather than a generic React app. The reader chooses style, colors, fonts, icons, and other options, clicks Create Project, selects a package manager, and copies the command. The resulting command looks like npx shadcn@latest init --preset [CODE] --template astro, with extra flags such as --base, --monorepo, or --rtl when selected.

Sources: apps/v4/content/docs/installation/astro.mdx, apps/v4/content/docs/installation/index.mdx

The second primitive is the shadcn CLI. For Astro, the direct terminal path is npx shadcn@latest init -t astro, followed by prompts for base, preset, monorepo, and related configuration. If the intended architecture is a workspace, the Astro guide shows npx shadcn@latest init -t astro --monorepo at project creation time. Choosing monorepo up front matters because later component installation and imports use the workspace app path and shared UI package instead of a single-app alias only.

Sources: apps/v4/content/docs/installation/astro.mdx

The third primitive is the import convention. In a single Astro app, the example imports Layout from @/layouts/main.astro and imports Card, CardContent, CardDescription, CardHeader, and CardTitle from @/components/ui/card. In a monorepo, the page path becomes apps/web/src/pages/index.astro, and the component import changes to @workspace/ui/components/card. The monorepo layout at apps/web/src/layouts/main.astro already imports @workspace/ui/globals.css, so the page can focus on using the component rather than repeating global style wiring.

Sources: apps/v4/content/docs/installation/astro.mdx

New Astro Project Flow

Use shadcn/create when you want the setup command to encode design decisions before the project is generated. Open the Astro create flow, build the preset visually, and copy the generated package-manager command. This is the most guided path for new apps because it makes style, color, font, icon, right-to-left, base, and monorepo decisions explicit before the CLI writes files. It also keeps Astro aligned with the broader installation overview, which presents create as the recommended path for new projects across supported frameworks.

npx shadcn@latest init --preset [CODE] --template astro

Use the direct CLI path when you prefer terminal prompts or already know that the target framework is Astro. The scaffold command is concise, and the guide immediately follows it with the component-add step because shadcn/ui becomes useful once components are written into the configured project. For a standard app, run the command without monorepo flags. For a workspace, include --monorepo during initialization rather than trying to retrofit the directory shape after components have already been installed.

npx shadcn@latest init -t astro
npx shadcn@latest init -t astro --monorepo

After initialization, install a concrete component to verify that configuration, aliases, styles, and generated paths all agree. The Astro guide uses the Card component because it demonstrates named exports and nested composition. In a single app, run npx shadcn@latest add card from the project root. In a monorepo, either run from apps/web or pass -c apps/web from the repository root so the CLI targets the correct workspace app configuration.

npx shadcn@latest add card
npx shadcn@latest add card -c apps/web

Sources: apps/v4/content/docs/installation/astro.mdx

Importing Components in Astro Pages

Astro files place imports in a frontmatter block, then render markup in the template body. The documented Card example follows that convention: import the layout and component exports at the top of src/pages/index.astro, then render the composed card inside Layout. The component source comes from the generated UI directory, so the import path is part of the installation contract. If the alias resolves correctly and the stylesheet is present, the card renders with the project’s selected shadcn/ui defaults.

---
import Layout from "@/layouts/main.astro"
import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@/components/ui/card"
---
 
<Layout>
  <Card className="max-w-sm">
    <CardHeader>
      <CardTitle>Project Overview</CardTitle>
      <CardDescription>
        Track progress and recent activity for your Astro app.
      </CardDescription>
    </CardHeader>
    <CardContent>
      Your design system is ready. Start building your next component.
    </CardContent>
  </Card>
</Layout>

For monorepos, keep the page-level Astro pattern but change the source of shared UI. The documented import is @workspace/ui/components/card, which signals that components live in a workspace UI package rather than only under the app’s local src tree. This distinction also explains why the add command can take -c apps/web: the CLI must know which app’s configuration to use while still allowing shared package imports. The generated monorepo layout handles @workspace/ui/globals.css so page authors import components, not global CSS, on every route.

Sources: apps/v4/content/docs/installation/astro.mdx

Existing Astro Projects and Manual Setup

Choose the existing-project path when the Astro app already exists and you do not want a generated template to make decisions for you. The installation overview says each framework guide includes existing-project instructions, and the manual guide exposes the common requirements underneath those flows. For Astro, that means Tailwind CSS must be installed, shadcn-related dependencies must be present, aliases must resolve to the directories where the CLI will write code, and global styles must include the shadcn Tailwind and theme layers.

Sources: apps/v4/content/docs/installation/astro.mdx, apps/v4/content/docs/installation/index.mdx, apps/v4/content/docs/installation/manual.mdx

The manual guide is especially important when adapting a custom Astro structure because it shows two alias strategies. One option is tsconfig.json paths such as @/*; another is package.json#imports with entries like #components/*, #lib/*, and #hooks/*, plus TypeScript settings for package import resolution. If you choose package imports, keep the matching alias roots in components.json; otherwise, later shadcn add commands may generate files in one place while imports refer to another convention.

Sources: apps/v4/content/docs/installation/manual.mdx

Neighboring framework pages clarify what is Astro-specific and what is shared installation mechanics. The Gatsby guide shows a Tailwind CSS v3 note, explicit tsconfig.json path configuration, and a gatsby-node.ts webpack alias setup before running npx shadcn@latest init. The Laravel guide shows the opposite contrast: the shadcn CLI does not scaffold Laravel, so the user creates the app with laravel new, selects the React starter kit, and then runs shadcn configuration commands. Astro is simpler for new projects because the supported template can be scaffolded directly with the CLI.

Sources: apps/v4/content/docs/installation/gatsby.mdx, apps/v4/content/docs/installation/laravel.mdx, apps/v4/content/docs/installation/astro.mdx

System-to-Code Mapping

Next Steps

Start with shadcn/create if the app is new and you want visual preset selection. Use init -t astro when the terminal prompt flow is enough, and decide on --monorepo before generating the project. After add card, verify the import path in src/pages/index.astro or apps/web/src/pages/index.astro, then continue to the CLI, components.json, package imports, theming, and monorepo pages when you need deeper control over where generated files live and how component imports resolve.