Astro

https://github.com/withastro/docs
Admin
Astro is an all-in-one web framework for building fast, content-focused websites, designed to help...
Tokens:664,647
Snippets:6,310
Trust Score:8.5
License:MIT
Update:23 hours ago
Show doc for...
Tokens:
Raw
### preview()

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/reference/programmatic-reference.mdx

Starts a local server to serve your build output programmatically. Similar to `astro preview`.

```APIDOC
## preview()

### Description
Similar to `astro preview`, it starts a local server to serve your build output.

If no adapter is set in the configuration, the preview server will only serve the built static files.
If an adapter is set in the configuration, the preview server is provided by the adapter. Adapters are not required to provide a preview server, so this feature may not be available depending on your adapter of choice.

### Method
Function

### Signature
`(inlineConfig: AstroInlineConfig) => Promise<PreviewServer>`

### Parameters
- **inlineConfig** (AstroInlineConfig) - Required - Configuration options for the preview server.

### Returns
A Promise that resolves to a `PreviewServer` object.

### Example
```js
import { preview } from "astro";

const previewServer = await preview({
  root: "./my-project",
});

// Stop the server if needed
await previewServer.stop();
```
```

--------------------------------

### Install project dependencies

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/install-and-setup.mdx

Run the install command if you skipped dependency installation during the CLI setup wizard before starting development.

```shell
npm install
```

```shell
pnpm install
```

```shell
yarn install
```

--------------------------------

### Start static site with Deno file server

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/deploy/deno.mdx

Serve static build output in the dist directory using the standard Deno HTTP file server.

```bash
deno run -A jsr:@std/http/file-server dist
```

--------------------------------

### Start local development server with Azion CLI

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/deploy/azion.mdx

Executes the local development server preview, running through the build process and providing a localhost access URL.

```bash
azion dev
```

```bash
Building your Edge Application. This process may take a few minutes
Running build step command:
...
```

```bash
[Azion Bundler] [Server] › ✔  success   Function running on port http://localhost:3000 
```

--------------------------------

### Start SSR site with Deno

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/deploy/deno.mdx

Run the server-rendered entrypoint file for SSR deployments using Deno.

```bash
deno run -A ./dist/server/entry.mjs
```

--------------------------------

### Launch the Astro setup wizard with pnpm

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/tutorial/1-setup/2.mdx

Run the `create astro` command using pnpm to launch the setup wizard. Specify a completely empty or non-existent folder when prompted for a directory.

```shell
# create a new project with pnpm
pnpm create astro@latest
```

--------------------------------

### Start preview server programmatically with preview()

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/reference/programmatic-reference.mdx

Starts a local server to serve the build output using the preview() function from "astro". Call stop() to shut down the server when done.

```javascript
import { preview } from "astro";

const previewServer = await preview({
  root: "./my-project",
});

// Stop the server if needed
await previewServer.stop();
```

--------------------------------

### Initialize demo workspace project with minimal template

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/integrations.mdx

Create a minimal Astro installation in the demo/ directory to test and demonstrate workspace packages during development.

```shell
npm create astro@latest demo -- --template minimal
```

```shell
pnpm create astro@latest demo -- --template minimal
```

```shell
yarn create astro demo --template minimal
```

--------------------------------

### Create a new Astro project using pnpm

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/migrate-to-astro/from-nuxtjs.mdx

Run the Astro CLI setup wizard or initialize a project using an official starter template via pnpm.

```shell
# launch the Astro CLI Wizard 
pnpm create astro@latest

# create a new project with an official example
pnpm create astro@latest --template <example-name>
```

--------------------------------

### Create a new Astro project using npm

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/migrate-to-astro/from-nuxtjs.mdx

Run the Astro CLI setup wizard or initialize a project using an official starter template via npm.

```shell
# launch the Astro CLI Wizard 
npm create astro@latest

# create a new project with an official example
npm create astro@latest -- --template <example-name>
```

--------------------------------

### Initialize project with Azion CLI

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/deploy/azion.mdx

Initializes and configures a new application in your project directory using the Azion CLI.

```bash
azion init
```

--------------------------------

### Initialize Fleek site project

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/deploy/fleek.mdx

Generates a configuration file for the site. Prompts to create a new site or use an existing one and select the project directory.

```bash
fleek sites init
```

--------------------------------

### Install Nginx and Git on VPS

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/deploy/ishosting.mdx

Run these commands on your VPS to install the Nginx web server and Git. Assumes you are logged in as root; use sudo if using another account.

```shell
apt update
apt install nginx git
```

--------------------------------

### Create project from template with --template flag

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/recipes/bun.mdx

Initialize an Astro project based on an official starter template or a GitHub repository's main branch.

```bash
# create a new project with an official example
bun create astro@latest --template <example-name>
# create a new project based on a GitHub repository’s main branch
bun create astro@latest --template <github-username>/<github-repo>
```

--------------------------------

### Clone, install, and build Astro project on VPS

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/deploy/ishosting.mdx

Clone your Astro repository to /var/www/astro, install dependencies, and build the site. Replace YOUR_REPOSITORY_URL with your actual repository URL.

```shell
cd /var/www
git clone YOUR_REPOSITORY_URL astro
cd astro
npm install
npm run build
```

--------------------------------

### Install Nano Stores for Solid

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/recipes/sharing-state-islands.mdx

Installs the core nanostores package along with the Solid integration helper.

```shell
npm install nanostores @nanostores/solid
```

--------------------------------

### Launch the Astro setup wizard with yarn

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/tutorial/1-setup/2.mdx

Run the `create astro` command with Yarn to launch the project creation tool. Choose a directory name that does not already exist when prompted.

```shell
# create a new project with yarn
yarn create astro
```

--------------------------------

### Create a new Astro project with npm

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/getting-started.mdx

Initializes a new Astro project using the interactive CLI wizard. For detailed setup steps and manual options, consult the installation guide.

```sh
# create a new project with npm
npm create astro@latest
```

--------------------------------

### Create project from theme or starter template

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/install-and-setup.mdx

Pass the `--template` flag to base a new Astro project on an official example or a GitHub repository main branch.

```shell
# create a new project with an official example
npm create astro@latest -- --template <example-name>

# create a new project based on a GitHub repository’s main branch
npm create astro@latest -- --template <github-username>/<github-repo>
```

```shell
# create a new project with an official example
pnpm create astro@latest --template <example-name>

# create a new project based on a GitHub repository’s main branch
pnpm create astro@latest --template <github-username>/<github-repo>
```

```shell
# create a new project with an official example
yarn create astro --template <example-name>

# create a new project based on a GitHub repository’s main branch
yarn create astro --template <github-username>/<github-repo>
```

--------------------------------

### Set up Git and Heroku app with static buildpack

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/deploy/heroku.mdx

Initialize git version control, create a new Heroku application, and set the static buildpack URL.

```bash
# version change
$ git init
$ git add .
$ git commit -m "My site ready for deployment."

# creates a new app with a specified name
$ heroku apps:create example

# set buildpack for static sites
$ heroku buildpacks:set https://github.com/heroku/heroku-buildpack-static.git
```

--------------------------------

### Install @astrojs/markdoc with astro add

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/integrations-guide/markdoc.mdx

Run the automated setup command using your preferred package manager to install and configure @astrojs/markdoc.

```sh
npx astro add markdoc
```

```sh
pnpm astro add markdoc
```

```sh
yarn astro add markdoc
```

--------------------------------

### Create a new Starlight documentation project

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/migrate-to-astro/from-docusaurus.mdx

Initializes a new Astro project configured with the official Starlight documentation starter template. Starlight includes MDX support by default so existing content can be brought over directly.

```shell
npm create astro@latest -- --template starlight
```

```shell
pnpm create astro@latest --template starlight
```

```shell
yarn create astro --template starlight
```

--------------------------------

### Initialize Prisma with database setup

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/backend/prisma-postgres.mdx

Initialize Prisma in your Astro project, configuring it to set up the database and output generated files to the specified directory.

```bash
npx prisma init --db --output ./generated
```

--------------------------------

### Create a new Astro project using Yarn

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/migrate-to-astro/from-nuxtjs.mdx

Run the Astro CLI setup wizard or initialize a project using an official starter template via Yarn.

```shell
# launch the Astro CLI Wizard 
yarn create astro@latest

# create a new project with an official example
yarn create astro@latest --template <example-name>
```

--------------------------------

### Create a new Astro and EmDash project

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/cms/emdash.mdx

Run the EmDash CLI to generate a pre-wired Astro and EmDash project from scratch.

```shell
npm create emdash@latest
```

```shell
pnpm create emdash@latest
```

```shell
yarn create emdash@latest
```

--------------------------------

### Create a new Astro project with the blog template

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/migrate-to-astro/from-wordpress.mdx

Run the create astro command with the --template blog argument to start a new Astro project using the official blog starter template.

```shell
npm create astro@latest -- --template blog
```

```shell
pnpm create astro@latest --template blog
```

```shell
yarn create astro --template blog
```

--------------------------------

### Configure start script in package.json

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/deploy/hostinger.mdx

Defines the start script to execute the standalone Node.js server entry point after building.

```json
{
  "scripts": {
    "start": "node ./dist/server/entry.mjs"
  }
}
```

--------------------------------

### Create a new Astro project using the blog template

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/migrate-to-astro/from-gridsome.mdx

Initialize a new Astro project configured with the official blog template starter using your preferred package manager. You can migrate existing Markdown or MDX files into this template.

```shell
npm create astro@latest -- --template blog
```

```shell
pnpm create astro@latest --template blog
```

```shell
yarn create astro --template blog
```

--------------------------------

### Replace start function with direct event listener

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/upgrade-to/v6.mdx

Removes the legacy start(manifest) function in favor of executing setup logic directly using createApp().

```js
import { App } from 'astro/app';

export function start(manifest) {
  const app = new App(manifest);

  addEventListener('fetch', event => {
    // ...
  });
}
import { createApp } from 'astro/app/entrypoint';

const app = createApp();

addEventListener('fetch', event => {
  // ...
});
```

--------------------------------

### Add start script to package.json

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/deploy/seenode.mdx

Defines a production start script to execute the built standalone server entry point.

```json
{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "start": "NODE_ENV=production node ./dist/server/entry.mjs"
  }
}
```

--------------------------------

### Example generated sitemap-index.xml and sitemap-0.xml files

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/integrations-guide/sitemap.mdx

Demonstrates the output structure created in the build directory for a two-page website. The index file links to numbered sitemap files listing individual pages.

```xml
<?xml version="1.0" encoding="UTF-8"?>
  <sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <sitemap>
    <loc>https://example.com/sitemap-0.xml</loc>
  </sitemap>
</sitemapindex>
```

```xml
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:news="http://www.google.com/schemas/sitemap-news/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1" xmlns:video="http://www.google.com/schemas/sitemap-video/1.1">
  <url>
    <loc>https://example.com/</loc>
  </url>
  <url>
    <loc>https://example.com/second-page/</loc>
  </url>
</urlset>
```

--------------------------------

### Install Nano Stores with pnpm

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/recipes/sharing-state.mdx

Install the nanostores package using pnpm.

```shell
pnpm add nanostores
```

--------------------------------

### Install PM2 and start Node.js server

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/deploy/ishosting.mdx

Install PM2 globally and start the Node.js server for an on-demand rendered site. The server runs on 127.0.0.1:4321 and is named astro-app.

```shell
npm install -g pm2
HOST=127.0.0.1 PORT=4321 pm2 start dist/server/entry.mjs --name astro-app
```

--------------------------------

### Install @astrojs/alpinejs using npm

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/integrations-guide/alpinejs.mdx

Run the automated Astro CLI setup command using npm to install and configure @astrojs/alpinejs.

```sh
npx astro add alpinejs
```

--------------------------------

### Configure start script in package.json

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/deploy/clever-cloud.mdx

Configure the start script in package.json for on-demand Node.js applications. Clever Cloud applications require the server to listen on host 0.0.0.0 and port 8080.

```json
"scripts": {
  "start": "node ./dist/server/entry.mjs --host 0.0.0.0 --port 8080",
}
```

--------------------------------

### Initialize StaticPaths instance in my-adapter/server.js

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/reference/modules/astro-static-paths.mdx

Demonstrates initializing a StaticPaths instance using an app instance in an adapter server entrypoint.

```javascript
import { createApp } from 'astro/app/entrypoint';
import { StaticPaths } from 'astro:static-paths';

const app = createApp();
const staticPaths = new StaticPaths(app);

export const handler = (event, context) => {
  // do something with `staticPaths`
};
```

--------------------------------

### Install Nano Stores with yarn

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/recipes/sharing-state.mdx

Install the nanostores package using yarn.

```shell
yarn add nanostores
```

--------------------------------

### Install Stylus preprocessor

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/styling.mdx

Installs the Stylus package to enable `<style lang="styl">` or `<style lang="stylus">` tags in `.astro` files.

```shell
npm install stylus
```

--------------------------------

### Install host CLI globally

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/deploy/index.mdx

Install your host's CLI globally using npm, pnpm, or yarn to configure and deploy your site from the command line.

```shell
npm install --global netlify-cli
```

```shell
pnpm add --global netlify-cli
```

```shell
yarn global add netlify-cli
```

--------------------------------

### Install Nano Stores with npm

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/recipes/sharing-state.mdx

Install the nanostores package using npm.

```shell
npm install nanostores
```

--------------------------------

### Install the @imagekit/video-player package

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/media/imagekit.mdx

Install `@imagekit/video-player` using your preferred package manager to use the native Astro video player component.

```shell
npm install @imagekit/video-player
```

```shell
pnpm add @imagekit/video-player
```

```shell
yarn add @imagekit/video-player
```

--------------------------------

### Install @astrojs/solid-js with astro add

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/integrations-guide/solid-js.mdx

Run the automated setup command from your project directory to install and configure @astrojs/solid-js.

```sh
npx astro add solid
```

```sh
pnpm astro add solid
```

```sh
yarn astro add solid
```

--------------------------------

### Start development server with astro dev

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/reference/cli-reference.mdx

Starts the Astro development server and provides a live updating preview of your site.

```shell
# start the development server
npx astro dev
```

```shell
# start the development server
pnpm astro dev
```

```shell
# start the development server
yarn astro dev
```

--------------------------------

### Open browser to /about on server start

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/reference/configuration-reference.mdx

Set server.open to a pathname or full URL to open in the browser when the dev server starts.

```js
// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  server: { open: "/about" }
});
```

--------------------------------

### Create project directory

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/install-and-setup.mdx

Creates an empty directory for the Astro project and navigates into it.

```bash
mkdir my-astro-project
cd my-astro-project
```

--------------------------------

### Create a new project using the toolbar-app template

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/recipes/making-toolbar-apps.mdx

Initialize a new Astro project pre-configured with the toolbar-app template using your preferred package manager.

```shell
npm create astro@latest -- --template toolbar-app
```

```shell
pnpm create astro -- --template toolbar-app
```

```shell
yarn create astro -- --template toolbar-app
```

--------------------------------

### Run development server with bun run dev

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/recipes/bun.mdx

Start the Astro local development server using Bun.

```bash
bun run dev
```

--------------------------------

### Update preview script in package.json

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/deploy/deno.mdx

Configure the `preview` script to execute the server entry file with required Deno network, read, and environment permissions.

```json
// package.json
{
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
    "preview": "deno run --allow-net --allow-read --allow-env ./dist/server/entry.mjs"
  }
}
```

--------------------------------

### Update start script in package.json

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/deploy/zerops.mdx

Configures the start script to run the server output generated by the Astro Node adapter.

```json
"scripts": {
  "start": "node ./dist/server/entry.mjs",
} 
```

--------------------------------

### build()

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/reference/programmatic-reference.mdx

Builds your site for deployment programmatically. Similar to `astro build`.

```APIDOC
## build()

### Description
Similar to `astro build`, it builds your site for deployment.

### Method
Function

### Signature
`(inlineConfig: AstroInlineConfig, options?: BuildOptions) => Promise<void>`

### Parameters
- **inlineConfig** (AstroInlineConfig) - Required - Configuration options for the build.
- **options** (BuildOptions) - Optional - Additional build options.

### Returns
A Promise that resolves when the build is complete.

### Example
```js
import { build } from "astro";

await build({
  root: "./my-project",
});
```
```

--------------------------------

### Install Nano Stores for Preact

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/recipes/sharing-state-islands.mdx

Installs the core nanostores package along with the Preact integration helper.

```shell
npm install nanostores @nanostores/preact
```

--------------------------------

### Install Nano Stores for React

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/recipes/sharing-state-islands.mdx

Installs the core nanostores package along with the React integration helper.

```shell
npm install nanostores @nanostores/react
```

--------------------------------

### Preview Astro site locally with Deno

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/deploy/deno.mdx

Execute the preview command using your preferred package manager to test your production build locally.

```shell
npm run preview
```

```shell
pnpm run preview
```

```shell
yarn run preview
```

--------------------------------

### Build site for production with bun run build

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/recipes/bun.mdx

Build the production version of your Astro site using Bun.

```bash
bun run build
```

--------------------------------

### Install Vercel CLI and deploy

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/deploy/vercel.mdx

Installs the Vercel CLI globally and triggers a deployment from the command line.

```shell
npm install -g vercel
vercel
```

```shell
pnpm add -g vercel
vercel
```

```shell
yarn global add vercel
vercel
```

--------------------------------

### Add start script to package.json

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/deploy/sevalla.mdx

Defines the start script required by Sevalla to run the built Astro standalone server entry point.

```json
"scripts": {
  "start": "node ./dist/server/entry.mjs"
}
```

--------------------------------

### Start Astro development server to run Keystatic

Source: https://github.com/withastro/docs/blob/main/src/content/docs/en/guides/cms/keystatic.mdx

Launches the Astro development server to access the Keystatic Admin UI dashboard locally at http://127.0.0.1:4321/keystatic.

```bash
npm run dev
```
Tokens:
Raw