Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 37 ยท Getting Started

The Astro CLI and Configuration

Learn the Astro CLI commands, how astro.config.mjs works with defineConfig, key options like site, base and output, plus env vars and TypeScript setup.

Two things control how an Astro project behaves: the command line interface you run and the configuration file that sits in the project root. Knowing them well saves time when you add integrations, change how URLs are generated or prepare for deployment.

The CLI

Astro installs a command named astro. You normally run it through npm scripts, but you can call it directly with npx astro.

Command What it does
astro dev Starts the dev server with hot reloading
astro build Builds the production site into dist/
astro preview Serves the built output locally
astro check Type-checks .astro and TypeScript files
astro add <name> Installs and configures an integration or adapter
astro sync Generates types for content collections and env
astro info Prints versions and environment details for bug reports

Useful flags include --port 3000 and --host (make the dev server reachable on your network) for dev and preview, --open to launch the browser and --config path to use a different config file.

Terminal
npx astro dev --port 3000 --open
npx astro add tailwind
npx astro check

astro add is especially helpful. It installs the package, edits astro.config.mjs and, for framework integrations, updates tsconfig.json. You can review the changes in Git before committing them.

Run astro check in continuous integration. It catches type errors in templates that astro build alone does not report.

astro.config.mjs

The config file exports an object. Wrapping it with defineConfig gives editors autocomplete and type checking.

JavaScript
// astro.config.mjs
import { defineConfig } from "astro/config";

export default defineConfig({
  site: "https://example.com",
  base: "/docs",
  output: "static",
  trailingSlash: "ignore",
  build: { format: "directory" },
  server: { port: 4321 },
  integrations: [],
});

The options you will meet most often:

  • site: the full production URL. Needed for sitemaps, canonical links and RSS.
  • base: a path prefix when the site lives in a subfolder, such as GitHub Pages at /my-repo. Internal links and assets then need the prefix too.
  • output: "static" (default) prerenders everything. "server" renders on demand unless a page opts out. Later chapters cover this.
  • trailingSlash: "always", "never" or "ignore" controls whether /about and /about/ are treated differently.
  • build.format: "directory" writes about/index.html; "file" writes about.html.
  • integrations: array of integration objects, such as React or a sitemap generator.
  • adapter: the deployment adapter for server output.
  • vite: raw Vite options, because Astro is built on Vite.

Config can also be written in TypeScript as astro.config.ts.

Environment variables

Astro loads .env files and exposes variables through import.meta.env:

TEXT
# .env
PUBLIC_SITE_NAME=My Site
SECRET_API_KEY=do-not-leak
ASTRO
---
const name = import.meta.env.PUBLIC_SITE_NAME;   // available in server and browser code
const key = import.meta.env.SECRET_API_KEY;      // server only
---

Only variables that start with PUBLIC_ are available in browser code. Others exist on the server, which keeps secrets out of client bundles. For typed, validated variables there is an env.schema option that you declare in the config and import from astro:env/client or astro:env/server.

TypeScript

New projects extend one of Astro's strictness presets from tsconfig.json:

JSON
{
  "extends": "astro/tsconfigs/strict",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"]
}

strict and strictest are good defaults. The file .astro/types.d.ts is generated, which is why astro sync exists. You can also add path aliases such as @components/* to compilerOptions.paths and then write import Card from "@components/Card.astro" from any depth.

Stand-in: merging defaults with your config

Astro merges the options you provide with its built-in defaults. This stand-in shows how defineConfig-style merging and validation work, including a check for a common mistake (a base without a leading slash).

Node.js Stand-in: config defaults and validation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Stand-in: a CLI dispatcher

A CLI is a table of command names mapped to functions, plus flag parsing. This stand-in handles dev --port 3000 the way a real tool might.

Node.js Stand-in: parse and dispatch commands

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Order of work for a new project

  1. Set site to the real domain.
  2. Run astro add for the integrations you know you need.
  3. Choose a tsconfig preset and add path aliases.
  4. Add npm scripts for check, for example "check": "astro check".
  5. Create .env and .env.example files; commit only the example.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command installs an integration and edits your config for you?

    astro add installs the package and updates astro.config.mjs (and tsconfig when needed).
  2. 2. What is the config option base for?

    base is used when the site lives under a path such as /my-repo, as with GitHub project pages.
  3. 3. Which environment variables can browser code read?

    Variables prefixed with PUBLIC_ are included in client code. Everything else stays on the server.
  4. 4. Why wrap the config object in defineConfig?

    defineConfig only returns what you give it. Its value is type information for your editor.

Summary

  • The astro CLI offers dev, build, preview, check, add, sync and info.
  • astro.config.mjs uses defineConfig; key options are site, base, output, build.format, integrations and adapter.
  • import.meta.env exposes .env values; only PUBLIC_ variables reach the browser.
  • Choose a strict tsconfig preset and run astro check in CI.
  • Astro is built on Vite, so Vite options can be passed through the vite key.

Next: File-Based Routing