Install and Setup

Purpose and Scope

This page explains the first setup decision for a new Astro project: whether to use the guided project creator or install the Astro package manually. The repository README presents the same split in a compact form, recommending the project creation command for most users while also showing a direct package install for manual setups. That matches the official installation guidance: the wizard is the fastest path because it creates the project shape, installs dependencies when requested, and gives follow-up instructions. Manual installation is still useful when you already have a project, a custom package layout, or a toolchain that should not be replaced. Sources: README.md, package.json

Astro is distributed as a command-line and package ecosystem, so setup is not just copying files. The repository root declares a private workspace, a required package manager for contributors, a Node engine requirement, and scripts that build, test, and typecheck the packages. For application developers, the practical prerequisite is a supported Node version and a terminal. For repository contributors, the root package metadata also signals that this monorepo expects pnpm and uses workspace filters to operate on the Astro package, integration packages, language tools, and examples. Sources: package.json

Recommended Path: Create a Project

The recommended command from the repository README is: npm create astro@latest. The official docs also show equivalent package-manager-specific forms, including pnpm create astro@latest and yarn create astro. This command invokes the create-astro workflow rather than merely adding a dependency. That distinction matters because a new website needs a project directory, starter files, scripts, and dependency installation. The wizard can be run from anywhere, and it can help create a directory if one does not already exist. After the wizard succeeds, the next normal step is to enter the project directory and begin running the generated development commands. Sources: README.md

Use the wizard when you want the least ambiguous setup path. It is designed for first projects, tutorials, and teams that want an official starter baseline before customizing. The official installation page notes that the wizard offers official starter templates, and the template flag can start from an existing theme or starter. That keeps installation aligned with Astro’s project model: pages, components, configuration, and dependencies are created together. In contrast, a plain dependency installation only gives you the package and leaves project structure and scripts for you to define. Sources: README.md

Manual Installation Path

Manual installation is the smaller operation: add the Astro package to an existing project with npm install astro, or the equivalent add/install command for your package manager. The README names this as the alternative for users who do not want the wizard. Manual setup is appropriate when a repository already has a package manifest, existing scripts, or a custom file layout. You should expect to create the supporting project files yourself, including Astro source directories, configuration, and package scripts. Manual installation is therefore more flexible, but it transfers responsibility from the wizard to the project maintainer. Sources: README.md

The core Astro CLI also contains an internal dependency installer for situations where a command needs an optional or required package that is not yet available. The getPackage helper first tries to resolve and import the requested package from the current working directory. If the package is missing and the dependency is not optional, Astro tells the user what must be installed, refuses automatic installation in CI, and otherwise delegates to an installer prompt. This makes setup interactive for local terminals but predictable in automation, where hidden package installation could make builds less reproducible. Sources: packages/astro/src/cli/install-package.ts

Package Manager and CI Behavior

Astro’s installer logic detects the package manager from installation metadata, lockfiles, or the package manager field, then asks package-manager-detector for the correct add command. If no manager is detected, npm is the fallback. Before running anything, Astro displays the command it plans to execute and explains that users can skip the step and run the command themselves later. This is an important setup affordance: the CLI can help, but it keeps the package operation visible so developers can understand and reproduce it in their own terminal. Sources: packages/astro/src/cli/install-package.ts

There are two edge cases worth knowing before scripting setup flows. First, Deno package installation requires an npm prefix, so the installer rewrites package names for a Deno command. Second, the installer resets NODE_ENV while running the add command so dependencies install in development mode. If the command fails, Astro logs debug information, shows a failed dependency message, and returns without importing the package. In CI, automatic installation is skipped entirely after the user-facing explanation, which means CI jobs should install all required dependencies explicitly before invoking Astro commands. Sources: packages/astro/src/cli/install-package.ts

Upgrade and Ongoing Setup

Initial setup is not the only time dependencies change. The upgrade package has its own install action for updating Astro-related packages. It separates already-current packages from dependencies and devDependencies that need updates, sorts display order so Astro and official packages are surfaced clearly, and flags major-version updates. When breaking changes are present, the action prompts before continuing and prints changelog guidance. Dry runs report what can be updated without installing anything. This mirrors the installation philosophy used elsewhere in the tooling: make package changes explicit, show intent before execution, and avoid surprising automation. Sources: packages/upgrade/src/actions/install.ts

The upgrade installer also resolves an add command through the detected package manager and treats Yarn specially by ensuring lockfile behavior before installation. This matters for teams that view setup as a lifecycle rather than a one-time action. A project created with the wizard will eventually need upgrades, and the upgrade tooling preserves dependency categories while giving maintainers a chance to review major changes. For production applications, that review step should be paired with the project’s normal build and test commands, especially before deploying a new Astro major version. Sources: packages/upgrade/src/actions/install.ts

Build Configuration Signals

The repository build configuration shows how Astro packages are prepared for publication and how package-level setup inherits common TypeScript settings. The shared build config extends a base TypeScript config, sets each package root directory to its source folder, emits output to a package dist directory, and stores TypeScript build metadata under a cache path inside dist. That cache location is intentionally chosen because it is ignored by npm publishing. Package-specific configs such as the Prism and RSS packages extend the shared build config, keeping build setup consistent across smaller packages. Sources: configs/tsconfig.build.json, packages/astro-prism/tsconfig.build.json, packages/astro-rss/tsconfig.build.json

This build setup is more relevant to contributors than to application authors, but it explains why the root repository setup is stricter than a normal generated project. The root package scripts run Turbo across selected workspaces, use pnpm workspaces, and provide commands for builds, examples, typechecking, linting, and tests. A user starting a website should follow the generated project’s scripts. A contributor working in this repository should respect the root workspace constraints, especially the pnpm-only preinstall guard and the Node engine requirement, because package builds and test tasks assume that environment. Sources: package.json, configs/tsconfig.build.json

The included changeset also shows why build and setup workflows must surface failures accurately. It records a Cloudflare adapter patch where prerender errors during workerd rendering were previously swallowed, causing a build to exit successfully while emitting truncated HTML. The fix buffers response bodies so streaming errors become build failures with clear messages. Although this is not an installation command, it is a setup signal for deployment-minded readers: after installing and configuring a project, treat astro build as the gate that validates rendering behavior before release. Sources: .changeset/sharp-bags-build.md

Relevant Source Files

• README.md — Presents the repository-level install promise: use npm create astro@latest as the recommended path, or manually install with npm install astro.
• package.json — Defines the monorepo’s Node engine, pnpm package manager requirement, workspaces, and contributor build/test scripts that shape repository setup.
• packages/astro/src/cli/install-package.ts — Implements Astro’s internal dependency resolution and interactive package installation behavior, including CI safeguards and package-manager detection.
• packages/upgrade/src/actions/install.ts — Implements dependency installation during upgrades, including dry runs, major-version prompts, changelog reminders, dependency grouping, and package-manager command resolution.
• .changeset/sharp-bags-build.md — Records a build-failure correctness fix that reinforces why setup workflows should rely on explicit build validation.
• configs/tsconfig.build.json — Provides shared TypeScript build output conventions used by package builds in the repository.
• packages/astro-prism/tsconfig.build.json — Shows a package-specific build config extending the shared build configuration while including virtual type declarations.
• packages/astro-rss/tsconfig.build.json — Shows another package-level build config that inherits the repository’s shared build defaults.

Practical Setup Flow

For a new application, start with the wizard command for your package manager, answer the prompts, then move into the generated directory. Install dependencies if the wizard did not do so, open the project in an editor with Astro language support, and run the generated development command. For an existing application, add the Astro package manually, then add the project files and scripts you need. For repository contribution, install with the declared pnpm version, satisfy the Node engine requirement, and use the root scripts for builds, typechecking, examples, and tests rather than treating the monorepo like a single generated app. Sources: README.md, package.json

After setup, the next pages to read depend on your goal. If you are learning the framework, continue to Project Structure and the pages/components/layouts tutorial. If you are documenting the CLI itself, read Create Astro CLI and CLI Reference. If you are maintaining an existing project, pair this page with Upgrade and Migration so dependency updates are handled deliberately. If you are preparing for deployment, read Develop, Build, and Test and the deployment overview before relying on a successful local install as proof that production rendering is ready.