Hello, World!
``` 4. Create your first static asset You will also want to create a `public/` directory to store your static assets. Astro will always include these assets in your final build, so you can safely reference them from inside your component templates. In your text editor, create a new file in your directory at `public/robots.txt`. `robots.txt` is a simple file that most sites will include to tell search bots like Google how to treat your site. For this guide, copy and paste the following code snippet into your new file: public/robots.txt ```diff # Example: Allow all bots to scan and index your site. # Full syntax: https://developers.google.com/search/docs/advanced/robots/create-robots-txt User-agent: * Allow: / ``` 5. Create `astro.config.mjs` Astro is configured using `astro.config.mjs`. This file is optional if you do not need to configure Astro, but you may wish to create it now. Create `astro.config.mjs` at the root of your project, and copy the code below into it: astro.config.mjs ```js import { defineConfig } from 'astro/config'; // https://astro.build/config export default defineConfig({}); ``` If you want to include [UI framework components](/en/guides/framework-components/) such as React, Svelte, etc. or use other tools such as Tailwind or Partytown in your project, here is where you will [manually import and configure integrations](/en/guides/integrations-guide/). Read Astro’s [API configuration reference](/en/reference/configuration-reference/) for more information. 6. Add TypeScript support TypeScript is configured using `tsconfig.json`. Even if you don’t write TypeScript code, this file is important so that tools like Astro and VS Code know how to understand your project. Some features (like npm package imports) aren’t fully supported in the editor without a `tsconfig.json` file. If you do intend to write TypeScript code, using Astro’s `strict` or `strictest` template is recommended. You can view and compare the three template configurations at [astro/tsconfigs/](https://github.com/withastro/astro/blob/main/packages/astro/tsconfigs/). Create `tsconfig.json` at the root of your project, and copy the code below into it. (You can use `base`, `strict`, or `strictest` for your TypeScript template): tsconfig.json ```json { "extends": "astro/tsconfigs/base" } ``` Read Astro’s [TypeScript setup guide](/en/guides/typescript/#setup) for more information. 7. Next Steps If you have followed the steps above, your project directory should now look like this: * astro.config.mjs * package-lock.json or `yarn.lock`, `pnpm-lock.yaml`, etc. * package.json * tsconfig.json 8. You can now [start the Astro dev server](/en/develop-and-build/#start-the-astro-dev-server) and see a live preview of your project while you build! # Project structure > An introduction to the basic file structure of an Astro project. Your new Astro project generated from the `create astro` CLI wizard already includes some files and folders. Others, you will create yourself and add to Astro’s existing file structure. Here’s how an Astro project is organized, and some files you will find in your new project. ## Directories and Files [Section titled Directories and Files](#directories-and-files) Astro leverages an opinionated folder layout for your project. Every Astro project root should include the following directories and files: * `src/*` - Your project source code (components, pages, styles, images, etc.) * `public/*` - Your non-code, unprocessed assets (fonts, icons, etc.) * `package.json` - A project manifest. * `astro.config.mjs` - An Astro configuration file. (recommended) * `tsconfig.json` - A TypeScript configuration file. (recommended) ### Example Project Tree [Section titled Example Project Tree](#example-project-tree) A common Astro project directory might look like this: * astro.config.mjs * package.json * tsconfig.json ### `src/` [Section titled src/](#src) The `src/` folder is where most of your project source code lives. This includes: * [Pages](/en/basics/astro-pages/) * [Layouts](/en/basics/layouts/) * [Astro components](/en/basics/astro-components/) * [UI framework components (React, etc.)](/en/guides/framework-components/) * [Styles (CSS, Sass)](/en/guides/styling/) * [Markdown](/en/guides/markdown-content/) * [Images to be optimized and processed by Astro](/en/guides/images/) Astro processes, optimizes, and bundles your `src/` files to create the final website that is shipped to the browser. Unlike the static `public/` directory, your `src/` files are built and handled for you by Astro. Some files (like Astro components) are not even sent to the browser as written but are instead rendered to static HTML. Other files (like CSS) are sent to the browser but may be optimized or bundled with other CSS files for performance. ### `src/pages` [Section titled src/pages](#srcpages) Pages routes are created for your site by adding [supported file types](/en/basics/astro-pages/#supported-page-files) to this directory. Caution `src/pages` is a **required** sub-directory in your Astro project. Without it, your site will have no pages or routes! ### `src/components` [Section titled src/components](#srccomponents) **Components** are reusable units of code for your HTML pages. These could be [Astro components](/en/basics/astro-components/), or [UI framework components](/en/guides/framework-components/) like React or Vue. It is common to group and organize all of your project components together in this folder. This is a common convention in Astro projects, but it is not required. Feel free to organize your components however you like! ### `src/layouts` [Section titled src/layouts](#srclayouts) [Layouts](/en/basics/layouts/) are Astro components that define the UI structure shared by one or more [pages](/en/basics/astro-pages/). Just like `src/components`, this directory is a common convention but not required. ### `src/styles` [Section titled src/styles](#srcstyles) It is a common convention to store your CSS or Sass files in a `src/styles` directory, but this is not required. As long as your styles live somewhere in the `src/` directory and are imported correctly, Astro will handle and optimize them. ### `public/` [Section titled public/](#public) The `public/` directory is for files and assets in your project that do not need to be processed during Astro’s build process. The files in this folder will be copied into the build folder untouched, and then your site will be built. This behavior makes `public/` ideal for common assets that do not require any processing, like some images and fonts, or special files such as `robots.txt` and `manifest.webmanifest`. You can place CSS and JavaScript in your `public/` directory, but be aware that those files will not be bundled or optimized in your final build. ### `package.json` [Section titled package.json](#packagejson) This is a file used by JavaScript package managers to manage your dependencies. It also defines the scripts that are commonly used to run Astro (ex: `npm run dev`, `npm run build`). There are [two kinds of dependencies](https://docs.npmjs.com/specifying-dependencies-and-devdependencies-in-a-package-json-file) you can specify in a `package.json`: `dependencies` and `devDependencies`. In most cases, these work the same: Astro needs all dependencies at build time, and your package manager will install both. We recommend putting all of your dependencies in `dependencies` to start, and only use `devDependencies` if you find a specific need to do so. For help creating a new `package.json` file for your project, check out the [manual setup](/en/install-and-setup/#manual-setup) instructions. ### `astro.config.mjs` [Section titled astro.config.mjs](#astroconfigmjs) This file is generated in every starter template and includes configuration options for your Astro project. Here you can specify integrations to use, build options, server options, and more. Astro supports several file formats for its JavaScript configuration file: `astro.config.js`, `astro.config.mjs`, `astro.config.cjs` and `astro.config.ts`. We recommend using `.mjs` in most cases or `.ts` if you want to write TypeScript in your config file. TypeScript config file loading is handled using [`tsm`](https://github.com/lukeed/tsm) and will respect your project’s `tsconfig` options. See the [configuration reference](/en/reference/configuration-reference/) for complete details. ### `tsconfig.json` [Section titled tsconfig.json](#tsconfigjson) This file is generated in every starter template and includes TypeScript configuration options for your Astro project. Some features (like npm package imports) aren’t fully supported in the editor without a `tsconfig.json` file. See the [TypeScript Guide](/en/guides/typescript/) for details on setting configurations. # Develop and build > How to start working on a new project. Once you have an Astro project, now you’re ready to build with Astro! 🚀 ## Edit your project [Section titled Edit your project](#edit-your-project) To make changes to your project, open your project folder in your code editor. Working in development mode with the dev server running allows you to see updates to your site as you edit the code. You can also [customize aspects of your development environment](#configure-your-dev-environment) such as configuring TypeScript or installing the official Astro editor extensions. ### Start the Astro dev server [Section titled Start the Astro dev server](#start-the-astro-dev-server) Astro comes with a built-in development server that has everything you need for project development. The `astro dev` CLI command will start the local development server so that you can see your new website in action for the very first time. Every starter template comes with a pre-configured script that will run `astro dev` for you. After navigating into your project directory, use your favorite package manager to run this command and start the Astro development server. * npm ```shell npm run dev ``` * pnpm ```shell pnpm run dev ``` * yarn ```shell yarn run dev ``` If all goes well, Astro will now be serving your project onTarget here
I was clicked!
``` See the [htmx documentation](https://htmx.org/docs/) for more details on using htmx.
# Layouts
> An introduction to layouts in Astro.
**Layouts** are [Astro components](/en/basics/astro-components/) used to provide a reusable UI structure, such as a page template. We conventionally use the term “layout” for Astro components that provide common UI elements shared across pages such as headers, navigation bars, and footers. A typical Astro layout component provides [Astro, Markdown or MDX pages](/en/basics/astro-pages/) with: * a **page shell** (``, `` and `` tags) * a [**`{title}
My page content, wrapped in a layout!
Published on {publishDate}
Viewed by {viewCount} folks
{frontmatter.title} by {frontmatter.author}
Written on: {frontmatter.date}
``` You can set a layout’s [`Props` type](/en/guides/typescript/#component-props) with the `MarkdownLayoutProps` helper: src/layouts/BlogPostLayout.astro ```astro --- import type { MarkdownLayoutProps } from 'astro'; type Props = MarkdownLayoutProps<{ // Define frontmatter props here title: string; author: string; date: string; }>; // Now, `frontmatter`, `url`, and other Markdown layout properties // are accessible with type safety const { frontmatter, url } = Astro.props; ---{frontmatter.title} by {frontmatter.author}
Written on: {frontmatter.date}
``` ### Markdown Layout Props [Section titled Markdown Layout Props](#markdown-layout-props) A Markdown layout will have access to the following information via `Astro.props`: * **`file`** - The absolute path of this file (e.g. `/home/user/projects/.../file.md`). * **`url`** - The URL of the page (e.g. `/en/guides/markdown-content`). * **`frontmatter`** - All frontmatter from the Markdown or MDX document. * **`frontmatter.file`** - The same as the top-level `file` property. * **`frontmatter.url`** - The same as the top-level `url` property. * **`headings`** - A list of headings (`h1 -> h6`) in the Markdown or MDX document with associated metadata. This list follows the type: `{ depth: number; slug: string; text: string }[]`. * **`rawContent()`** - A function that returns the raw Markdown document as a string. * **`compiledContent()`** - An async function that returns the Markdown document compiled to an HTML string. ### Importing Layouts Manually (MDX) [Section titled Importing Layouts Manually (MDX)](#importing-layouts-manually-mdx) You can also use the special Markdown layout property in the frontmatter of MDX files to pass `frontmatter` and `headings` props directly to a specified layout component in the same way. To pass information to your MDX layout that does not (or cannot) exist in your frontmatter, you can instead import and use a `{title}
{fancyJsHelper()}
``` When using any layout (either through the frontmatter `layout` property or by importing a layout), you must include the `` tag in your layout as Astro will no longer add it automatically to your MDX page. Learn more about Astro’s Markdown and MDX support in our [Markdown guide](/en/guides/markdown-content/). ## Nesting Layouts [Section titled Nesting Layouts](#nesting-layouts) Layout components do not need to contain an entire page worth of HTML. You can break your layouts into smaller components, and combine layout components to create even more flexible, page templates. This pattern is useful when you want to share some code across multiple layouts. For example, a `BlogPostLayout.astro` layout component could style a post’s title, date and author. Then, a site-wide `BaseLayout.astro` could handle the rest of your page template, like navigation, footers, SEO meta tags, global styles, and fonts. You can also pass props received from your post to another layout, just like any other nested component. src/layouts/BlogPostLayout.astro ```astro --- import BaseLayout from './BaseLayout.astro'; const { frontmatter } = Astro.props; ---{frontmatter.title}
Post author: {frontmatter.author}
Unable to sign up. Please try again later.
)} ``` For more customization, you can [use the `isInputError()` utility](#displaying-form-input-errors) to check whether an error is caused by invalid input. The following example renders an error banner under the `email` input field when an invalid email is submitted: src/pages/index.astro ```astro --- import { actions, isInputError } from 'astro:actions'; const result = Astro.getActionResult(actions.newsletter); const inputErrors = isInputError(result?.error) ? result.error.fields : {}; --- ``` #### Preserve input values on error [Section titled Preserve input values on error](#preserve-input-values-on-error) Inputs will be cleared whenever a form is submitted. To persist input values, you can [enable view transitions](/en/guides/view-transitions/#adding-view-transitions-to-a-page) on the page and apply the `transition:persist` directive to each input: ```astro ``` ### Update the UI with a form action result [Section titled Update the UI with a form action result](#update-the-ui-with-a-form-action-result) To use an action’s return value to display a notification to the user on success, pass the action to `Astro.getActionResult()`. Use the returned `data` property to render the UI you want to display. This example uses the `productName` property returned by an `addToCart` action to show a success message. src/pages/products/\[slug].astro ```astro --- import { actions } from 'astro:actions'; const result = Astro.getActionResult(actions.addToCart); --- {result && !result.error && (Added {result.data.productName} to cart
)} ``` ### Advanced: Persist action results with a session [Section titled Advanced: Persist action results with a session](#advanced-persist-action-results-with-a-session) **Added in:** `astro@5.0.0` Action results are displayed as a POST submission. This means that the result will be reset to `undefined` when a user closes and revisits the page. The user will also see a “confirm form resubmission?” dialog if they attempt to refresh the page. To customize this behavior, you can add middleware to handle the result of the action manually. You may choose to persist the action result using a cookie or session storage. Start by [creating a middleware file](/en/guides/middleware/) and importing [the `getActionContext()` utility](/en/reference/modules/astro-actions/#getactioncontext) from `astro:actions`. This function returns an `action` object with information about the incoming action request, including the action handler and whether the action was called from an HTML form. `getActionContext()` also returns the `setActionResult()` and `serializeActionResult()` functions to programmatically set the value returned by `Astro.getActionResult()`: src/middleware.ts ```ts import { defineMiddleware } from 'astro:middleware'; import { getActionContext } from 'astro:actions'; export const onRequest = defineMiddleware(async (context, next) => { const { action, setActionResult, serializeActionResult } = getActionContext(context); if (action?.calledFrom === 'form') { const result = await action.handler(); // ... handle the action result setActionResult(action.name, serializeActionResult(result)); } return next(); }); ``` A common practice to persist HTML form results is the [POST / Redirect / GET pattern](https://en.wikipedia.org/wiki/Post/Redirect/Get). This redirect removes the “confirm form resubmission?” dialog when the page is refreshed, and allows action results to be persisted throughout the user’s session. This example applies the POST / Redirect / GET pattern to all form submissions using session storage with the [Netlify server adapter](/en/guides/integrations-guide/netlify/) installed. Action results are written to a session store using [Netlify Blob](https://docs.netlify.com/blobs/overview/), and retrieved after a redirect using a session ID: src/middleware.ts ```ts import { defineMiddleware } from 'astro:middleware'; import { getActionContext } from 'astro:actions'; import { randomUUID } from "node:crypto"; import { getStore } from "@netlify/blobs"; export const onRequest = defineMiddleware(async (context, next) => { // Skip requests for prerendered pages if (context.isPrerendered) return next(); const { action, setActionResult, serializeActionResult } = getActionContext(context); // Create a Blob store to persist action results with Netlify Blob const actionStore = getStore("action-session"); // If an action result was forwarded as a cookie, set the result // to be accessible from `Astro.getActionResult()` const sessionId = context.cookies.get("action-session-id")?.value; const session = sessionId ? await actionStore.get(sessionId, { type: "json", }) : undefined; if (session) { setActionResult(session.actionName, session.actionResult); // Optional: delete the session after the page is rendered. // Feel free to implement your own persistence strategy await actionStore.delete(sessionId); context.cookies.delete("action-session-id"); return next(); } // If an action was called from an HTML form action, // call the action handler and redirect to the destination page if (action?.calledFrom === "form") { const actionResult = await action.handler(); // Persist the action result using session storage const sessionId = randomUUID(); await actionStore.setJSON(sessionId, { actionName: action.name, actionResult: serializeActionResult(actionResult), }); // Pass the session ID as a cookie // to be retrieved after redirecting to the page context.cookies.set("action-session-id", sessionId); // Redirect back to the previous page on error if (actionResult.error) { const referer = context.request.headers.get("Referer"); if (!referer) { throw new Error( "Internal: Referer unexpectedly missing from Action POST request.", ); } return context.redirect(referer); } // Redirect to the destination page on success return context.redirect(context.originPathname); } return next(); }); ``` ## Security when using actions [Section titled Security when using actions](#security-when-using-actions) Actions are accessible as public endpoints based on the name of the action. For example, the action `blog.like()` will be accessible from `/_actions/blog.like`. This is useful for unit testing action results and debugging production errors. However, this means you **must** use same authorization checks that you would consider for API endpoints and on-demand rendered pages. ### Authorize users from an action handler [Section titled Authorize users from an action handler](#authorize-users-from-an-action-handler) To authorize action requests, add an authentication check to your action handler. You may want to use [an authentication library](/en/guides/authentication/) to handle session management and user information. Actions expose the full `APIContext` object to access properties passed from middleware using `context.locals`. When a user is not authorized, you can raise an `ActionError` with the `UNAUTHORIZED` code: src/actions/index.ts ```ts import { defineAction, ActionError } from 'astro:actions'; export const server = { getUserSettings: defineAction({ handler: async (_input, context) => { if (!context.locals.user) { throw new ActionError({ code: 'UNAUTHORIZED' }); } return { /* data on success */ }; } }) } ``` ### Gate actions from middleware [Section titled Gate actions from middleware](#gate-actions-from-middleware) **Added in:** `astro@5.0.0` Astro recommends authorizing user sessions from your action handler to respect permission levels and rate-limiting on a per-action basis. However, you can also gate requests to all actions (or a subset of actions) from middleware. Use the `getActionContext()` function from your middleware to retrieve information about any inbound action requests. This includes the action name and whether that action was called using a client-side remote procedure call (RPC) function (e.g. `actions.blog.like()`) or an HTML form. The following example rejects all action requests that do not have a valid session token. If the check fails, a “Forbidden” response is returned. Note: this method ensures that actions are only accessible when a session is present, but is *not* a substitute for secure authorization. src/middleware.ts ```ts import { defineMiddleware } from 'astro:middleware'; import { getActionContext } from 'astro:actions'; export const onRequest = defineMiddleware(async (context, next) => { const { action } = getActionContext(context); // Check if the action was called from a client-side function if (action?.calledFrom === 'rpc') { // If so, check for a user session token if (context.cookies.has('user-session')) { return new Response('Forbidden', { status: 403 }); } } context.cookies.set('user-session', /* session token */); return next(); }); ``` ## Call actions from Astro components and server endpoints [Section titled Call actions from Astro components and server endpoints](#call-actions-from-astro-components-and-server-endpoints) You can call actions directly from Astro component scripts using the `Astro.callAction()` wrapper (or `context.callAction()` when using a [server endpoint](/en/guides/endpoints/#server-endpoints-api-routes)). This is common to reuse logic from your actions in other server code. Pass the action as the first argument and any input parameters as the second argument. This returns the same `data` and `error` objects you receive when calling actions on the client: src/pages/products.astro ```astro --- import { actions } from 'astro:actions'; const searchQuery = Astro.url.searchParams.get('search'); if (searchQuery) { const { data, error } = await Astro.callAction(actions.findProduct, { query: searchQuery }); // handle result } --- ``` # Astro DB > Learn how to use Astro DB, a fully-managed SQL database designed exclusively for Astro. Astro DB is a fully-managed SQL database designed for the Astro ecosystem. Develop locally in Astro and deploy to any libSQL-compatible database. Astro DB is a complete solution to configuring, developing, and querying your data. A local database is created in `.astro/content.db` whenever you run `astro dev` to manage your data without the need for Docker or a network connection. ## Installation [Section titled Installation](#installation) Install the [`@astrojs/db` integration](/en/guides/integrations-guide/db/) using the built-in `astro add` command: * npm ```sh npx astro add db ``` * pnpm ```sh pnpm astro add db ``` * Yarn ```sh yarn astro add db ``` ## Define your database [Section titled Define your database](#define-your-database) Installing `@astrojs/db` with the `astro add` command will automatically create a `db/config.ts` file in your project where you will define your database tables: db/config.ts ```ts import { defineDb } from 'astro:db'; export default defineDb({ tables: { }, }) ``` ### Tables [Section titled Tables](#tables) Data in Astro DB is stored using SQL tables. Tables structure your data into rows and columns, where columns enforce the type of each row value. Define your tables in your `db/config.ts` file by providing the structure of the data in your existing libSQL database, or the data you will collect in a new database. This will allow Astro to generate a TypeScript interface to query that table from your project. The result is full TypeScript support when you access your data with property autocompletion and type-checking. To configure a database table, import and use the `defineTable()` and `column` utilities from `astro:db`. Then, define a name (case-sensitive) for your table and the type of data in each column. This example configures a `Comment` table with required text columns for `author` and `body`. Then, makes it available to your project through the `defineDb()` export. db/config.ts ```ts import { defineDb, defineTable, column } from 'astro:db'; const Comment = defineTable({ columns: { author: column.text(), body: column.text(), } }) export default defineDb({ tables: { Comment }, }) ``` See the [table configuration reference](/en/guides/integrations-guide/db/#table-configuration-reference) for a complete reference of table options. ### Columns [Section titled Columns](#columns) Astro DB supports the following column types: db/config.ts ```ts import { defineTable, column } from 'astro:db'; const Comment = defineTable({ columns: { // A string of text. author: column.text(), // A whole integer value. likes: column.number(), // A true or false value. flagged: column.boolean(), // Date/time values queried as JavaScript Date objects. published: column.date(), // An untyped JSON object. metadata: column.json(), } }); ``` See the [table columns reference](/en/guides/integrations-guide/db/#table-configuration-reference) for more details. ### Table References [Section titled Table References](#table-references) Relationships between tables are a common pattern in database design. For example, a `Blog` table may be closely related to other tables of `Comment`, `Author`, and `Category`. You can define these relations between tables and save them into your database schema using **reference columns**. To establish a relationship, you will need: * An **identifier column** on the referenced table. This is usually an `id` column with the `primaryKey` property. * A column on the base table to **store the referenced `id`**. This uses the `references` property to establish a relationship. This example shows a `Comment` table’s `authorId` column referencing an `Author` table’s `id` column. db/config.ts ```ts const Author = defineTable({ columns: { id: column.number({ primaryKey: true }), name: column.text(), } }); const Comment = defineTable({ columns: { authorId: column.number({ references: () => Author.columns.id }), body: column.text(), } }); ``` ## Seed your database for development [Section titled Seed your database for development](#seed-your-database-for-development) In development, Astro will use your DB config to generate local types according to your schemas. These will be generated fresh from your seed file each time the dev server is started, and will allow you to query and work with the shape of your data with type safety and autocompletion. You will not have access to production data during development unless you [connect to a remote database](#connecting-to-remote-databases) during development. This protects your data while allowing you to test and develop with a working database with type-safety. To seed development data for testing and debugging into your Astro project, create a `db/seed.ts` file. Import both the `db` object and your tables defined in `astro:db`. `insert` some initial data into each table. This development data should match the form of both your database schema and production data. The following example defines two rows of development data for a `Comment` table, and an `Author` table: db/seed.ts ```ts import { db, Comment, Author } from 'astro:db'; export default async function() { await db.insert(Author).values([ { id: 1, name: "Kasim" }, { id: 2, name: "Mina" }, ]); await db.insert(Comment).values([ { authorId: 1, body: 'Hope you like Astro DB!' }, { authorId: 2, body: 'Enjoy!'}, ]) } ``` Your development server will automatically restart your database whenever this file changes, regenerating your types and seeding this development data from `seed.ts` fresh each time. ## Connect a libSQL database for production [Section titled Connect a libSQL database for production](#connect-a-libsql-database-for-production) Astro DB can connect to any local libSQL database or to any server that exposes the libSQL remote protocol, whether managed or self-hosted. To connect Astro DB to a libSQL database, set the following environment variables obtained from your database provider: * `ASTRO_DB_REMOTE_URL`: the connection URL to the location of your local or remote libSQL DB. This may include [URL configuration options](#remote-url-configuration-options) such as sync and encryption as parameters. * `ASTRO_DB_APP_TOKEN`: the auth token to your libSQL server. This is required for remote databases, and not needed for [local DBs like files or in-memory](#url-scheme-and-host) databases Depending on your service, you may have access to a CLI or web UI to retrieve these values. The following section will demonstrate connecting to Turso and setting these values as an example, but you are free to use any provider. ### Getting started with Turso [Section titled Getting started with Turso](#getting-started-with-turso) Turso is the company behind [libSQL](https://github.com/tursodatabase/libsql), the open-source fork of SQLite that powers Astro DB. They provide a fully managed libSQL database platform and are fully compatible with Astro. The steps below will guide you through the process of installing the Turso CLI, logging in (or signing up), creating a new database, getting the required environmental variables, and pushing the schema to the remote database. 1. Install the [Turso CLI](https://docs.turso.tech/cli/installation). 2. [Log in or sign up](https://docs.turso.tech/cli/authentication) to Turso. 3. Create a new database. In this example the database name is `andromeda`. ```sh turso db create andromeda ``` 4. Run the `show` command to see information about the newly created database: ```sh turso db show andromeda ``` Copy the `URL` value and set it as the value for `ASTRO_DB_REMOTE_URL`. .env ```dotenv ASTRO_DB_REMOTE_URL=libsql://andromeda-houston.turso.io ``` 5. Create a new token to authenticate requests to the database: ```sh turso db tokens create andromeda ``` Copy the output of the command and set it as the value for `ASTRO_DB_APP_TOKEN`. .env ```dotenv ASTRO_DB_REMOTE_URL=libsql://andromeda-houston.turso.io ASTRO_DB_APP_TOKEN=eyJhbGciOiJF...3ahJpTkKDw ``` 6. Push your DB schema and metadata to the new Turso database. ```sh astro db push --remote ``` 7. Congratulations, now you have a database connected! Give yourself a break. 👾 ```sh turso relax ``` To explore more features of Turso, check out the [Turso docs](https://docs.turso.tech). ### Connecting to remote databases [Section titled Connecting to remote databases](#connecting-to-remote-databases) Astro DB allows you to connect to both local and remote databases. By default, Astro uses a local database file for `dev` and `build` commands, recreating tables and inserting development seed data each time. To connect to a hosted remote database, use the `--remote` flag. This flag enables both readable and writable access to your remote database, allowing you to [accept and persist user data](#insert) in production environments. Configure your build command to use the `--remote` flag: package.json ```json { "scripts": { "build": "astro build --remote" } } ``` You can also use the flag directly in the command line: ```bash # Build with a remote connection astro build --remote # Develop with a remote connection astro dev --remote ``` Caution Be careful when using `--remote` in development. This connects to your live production database, and all changes (inserts, updates, deletions) will be persisted. The `--remote` flag uses the connection to the remote DB both locally during the build and on the server. Ensure you set the necessary environment variables in both your local development environment and your deployment platform. When deploying your Astro DB project, make sure your deployment platform’s build command is set to `npm run build` (or the equivalent for your package manager) to utilize the `--remote` flag configured in your `package.json`. ### Remote URL configuration options [Section titled Remote URL configuration options](#remote-url-configuration-options) The `ASTRO_DB_REMOTE_URL` environment variable configures the location of your database as well as other options like sync and encryption. #### URL scheme and host [Section titled URL scheme and host](#url-scheme-and-host) libSQL supports both HTTP and WebSockets as the transport protocol for a remote server. It also supports using a local file or an in-memory DB. Those can be configured using the following URL schemes in the connection URL: * `memory:` will use an in-memory DB. The host must be empty in this case. * `file:` will use a local file. The host is the path to the file (`file:path/to/file.db`). * `libsql:` will use a remote server through the protocol preferred by the library (this might be different across versions). The host is the address of the server (`libsql://your.server.io`). * `http:` will use a remote server through HTTP. `https:` can be used to enable a secure connection. The host is the same as for `libsql:`. * `ws:` will use a remote server through WebSockets. `wss:` can be used to enable a secure connection. The host is the same as for `libsql:`. Details of the libSQL connection (e.g. encryption key, replication, sync interval) can be configured as query parameters in the remote connection URL. For example, to have an encrypted local file work as an embedded replica to a libSQL server, you can set the following environment variables: .env ```dotenv ASTRO_DB_REMOTE_URL=file://local-copy.db?encryptionKey=your-encryption-key&syncInterval=60&syncUrl=libsql%3A%2F%2Fyour.server.io ASTRO_DB_APP_TOKEN=token-to-your-remote-url ``` Caution Using a database file is an advanced feature, and care should be taken when deploying to prevent overriding your database and losing your production data. Additionally, this method will not work in serverless deployments, as the file system is not persisted in those environments. #### `encryptionKey` [Section titled encryptionKey](#encryptionkey) libSQL has native support for encrypted databases. Passing this search parameter will enable encryption using the given key: .env ```dotenv ASTRO_DB_REMOTE_URL=file:path/to/file.db?encryptionKey=your-encryption-key ``` #### `syncUrl` [Section titled syncUrl](#syncurl) Embedded replicas are a feature of libSQL clients that creates a full synchronized copy of your database on a local file or in memory for ultra-fast reads. Writes are sent to a remote database defined on the `syncUrl` and synchronized with the local copy. Use this property to pass a separate connection URL to turn the database into an embedded replica of another database. This should only be used with the schemes `file:` and `memory:`. The parameter must be URL encoded. For example, to have an in-memory embedded replica of a database on `libsql://your.server.io`, you can set the connection URL as such: .env ```dotenv ASTRO_DB_REMOTE_URL=memory:?syncUrl=libsql%3A%2F%2Fyour.server.io ``` #### `syncInterval` [Section titled syncInterval](#syncinterval) Interval between embedded replica synchronizations in seconds. By default it only synchronizes on startup and after writes. This property is only used when `syncUrl` is also set. For example, to set an in-memory embedded replica to synchronize every minute set the following environment variable: .env ```dotenv ASTRO_DB_REMOTE_URL=memory:?syncUrl=libsql%3A%2F%2Fyour.server.io&syncInterval=60 ``` ## Query your database [Section titled Query your database](#query-your-database) You can query your database from any [Astro page](/en/basics/astro-pages/#astro-pages), [endpoint](/en/guides/endpoints/), or [action](/en/guides/actions/) in your project using the provided `db` ORM and query builder. ### Drizzle ORM [Section titled Drizzle ORM](#drizzle-orm) ```ts import { db } from 'astro:db'; ``` Astro DB includes a built-in [Drizzle ORM](https://orm.drizzle.team/) client. There is no setup or manual configuration required to use the client. The Astro DB `db` client is automatically configured to communicate with your database (local or remote) when you run Astro. It uses your exact database schema definition for type-safe SQL queries with TypeScript errors when you reference a column or table that doesn’t exist. ### Select [Section titled Select](#select) The following example selects all rows of a `Comment` table. This returns the complete array of seeded development data from `db/seed.ts` which is then available for use in your page template: src/pages/index.astro ```astro --- import { db, Comment } from 'astro:db'; const comments = await db.select().from(Comment); ---Comments
{ comments.map(({ author, body }) => (Author: {author}
{body}
Comments
{ comments.map(({ Author, Comment }) => (Author: {Author.name}
{Comment.body}
Use React components directly in Astro!
Here is a sidebar with some text and a button.
Menu
Here is a sidebar with some text and a button.
Here is a sidebar with some text and a button.
Lorem ipsum
{entry.data.title}
one
two
Name:
{/* Luke Skywalker */}{name()}
); } ``` Similarly, Solid’s [Lazy Components](https://www.solidjs.com/docs/latest/api#lazy) will also be resolved and their HTML will be included in the initial server-rendered page. Non-hydrating [`client:only` components](/en/reference/directives-reference/#clientonly) are not automatically wrapped in Suspense boundaries. Feel free to add additional Suspense boundaries according to your preference.
# @astrojs/svelte
> Learn how to use the @astrojs/svelte framework integration to extend component support in your Astro project.
This **[Astro integration](/en/guides/integrations-guide/)** enables rendering and client-side hydration for your [Svelte](https://svelte.dev/) 5 components. For Svelte 3 and 4 support, install `@astrojs/svelte@5` instead. ## Installation [Section titled Installation](#installation) Astro includes an `astro add` command to automate the setup of official integrations. If you prefer, you can [install integrations manually](#manual-install) instead. To install `@astrojs/svelte`, run the following from your project directory and follow the prompts: * npm ```sh npx astro add svelte ``` * pnpm ```sh pnpm astro add svelte ``` * Yarn ```sh yarn astro add svelte ``` If you run into any issues, [feel free to report them to us on GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below. ### Manual Install [Section titled Manual Install](#manual-install) First, install the `@astrojs/svelte` package: * npm ```sh npm install @astrojs/svelte ``` * pnpm ```sh pnpm add @astrojs/svelte ``` * Yarn ```sh yarn add @astrojs/svelte ``` Most package managers will install associated peer dependencies as well. If you see a `Cannot find package 'svelte'` (or similar) warning when you start up Astro, you’ll need to install Svelte and TypeScript: * npm ```sh npm install svelte typescript ``` * pnpm ```sh pnpm add svelte typescript ``` * Yarn ```sh yarn add svelte typescript ``` Then, apply the integration to your `astro.config.*` file using the `integrations` property: astro.config.mjs ```js import { defineConfig } from 'astro/config'; import svelte from '@astrojs/svelte'; export default defineConfig({ // ... integrations: [svelte()], }); ``` And create a new file called `svelte.config.js` in your project root directory and add the following code: svelte.config.js ```js import { vitePreprocess } from '@astrojs/svelte'; export default { preprocess: vitePreprocess(), } ``` ## Getting started [Section titled Getting started](#getting-started) To use your first Svelte component in Astro, head to our [UI framework documentation](/en/guides/framework-components/#using-framework-components). You’ll explore: * 📦 how framework components are loaded, * 💧 client-side hydration options, and * 🤝 opportunities to mix and nest frameworks together ## Options [Section titled Options](#options) This integration is powered by `@sveltejs/vite-plugin-svelte`. To customize the Svelte compiler, options can be provided to the integration. See the [`@sveltejs/vite-plugin-svelte` docs](https://github.com/sveltejs/vite-plugin-svelte/blob/HEAD/docs/config.md) for more details. You can set options either by passing them to the `svelte` integration in `astro.config.mjs` or in `svelte.config.js`. The options in `astro.config.mjs` will take precedence over the options in `svelte.config.js` if both are present: astro.config.mjs ```js import { defineConfig } from 'astro/config'; import svelte from '@astrojs/svelte'; export default defineConfig({ integrations: [svelte({ extensions: ['.svelte'] })], }); ``` svelte.config.js ```js export default { extensions: ['.svelte'], }; ``` ## Preprocessors [Section titled Preprocessors](#preprocessors) **Added in:** `@astrojs/svelte@2.0.0` If you’re using SCSS or Stylus in your Svelte files, you can create a `svelte.config.js` file so that they are preprocessed by Svelte, and the Svelte IDE extension can correctly parse the Svelte files. svelte.config.js ```js import { vitePreprocess } from '@astrojs/svelte'; export default { preprocess: vitePreprocess(), }; ``` This config file will be automatically added for you when you run `astro add svelte`. See the [`@sveltejs/vite-plugin-svelte` docs](https://github.com/sveltejs/vite-plugin-svelte/blob/HEAD/docs/preprocess.md) for more details about `vitePreprocess`.
# @astrojs/tailwind
> Learn how to use the @astrojs/tailwind integration in your Astro project.
This **[Astro integration](/en/guides/integrations-guide/)** brings [Tailwind’s](https://tailwindcss.com/) utility CSS classes to every `.astro` file and [framework component](/en/guides/framework-components/) in your project, along with support for the Tailwind configuration file. ## Why Tailwind? [Section titled Why Tailwind?](#why-tailwind) Tailwind lets you use utility classes instead of writing CSS. These utility classes are mostly one-to-one with a certain CSS property setting: for example, adding the `text-lg` to an element is equivalent to setting `font-size: 1.125rem` in CSS. You might find it easier to write and maintain your styles using these predefined utility classes! If you don’t like those predefined settings, you can [customize the Tailwind configuration file](https://tailwindcss.com/docs/configuration) to your project’s design requirements. For example, if the “large text” in your design is actually `2rem`, you can [change the `lg` fontSize setting](https://tailwindcss.com/docs/font-size#customizing-your-theme) to `2rem`. Tailwind is also a great choice to add styles to React, Preact, or Solid components, which don’t support a ` ``` ### Scoped Styles [Section titled Scoped Styles](#scoped-styles) Astro ` ``` Compiles to this: ```astro ``` Scoped styles don’t leak and won’t impact the rest of your site. In Astro, it is okay to use low-specificity selectors like `h1 {}` or `p {}` because they will be compiled with scopes in the final output. Scoped styles also won’t apply to other Astro components contained inside of your template. If you need to style a child component, consider wrapping that component in a `` (or other element) that you can then style. The specificity of scoped styles is preserved, allowing them to work consistently alongside other CSS files or CSS libraries while still preserving the exclusive boundaries that prevent styles from applying outside the component. ### Global Styles [Section titled Global Styles](#global-styles) While we recommend scoped styles for most components, you may eventually find a valid reason to write global, unscoped CSS. You can opt-out of automatic CSS scoping with the ` ``` You can also mix global & scoped CSS rules together in the same ` This will be red! ``` ### Inline styles [Section titled Inline styles](#inline-styles) You can style HTML elements inline using the `style` attribute. This can be a CSS string or an object of CSS properties: src/pages/index.astro ```astro // These are equivalent: ``` If two rules have the same specificity, then the *order of appearance* is evaluated, and the last rule’s value will take precedence: src/components/MyComponent.astro ```astro ``` Astro CSS rules are evaluated in this order of appearance: * **`` tags in the head** (lowest precedence) * **imported styles** * **scoped styles** (highest precedence) ### Scoped Styles [Section titled Scoped Styles](#scoped-styles-1) Using [scoped styles](#scoped-styles) does not increase the *specificity* of your CSS, but they will always come last in the *order of appearance*. They will therefore take precedence over other styles of the same specificity. For example, if you import a stylesheet that conflicts with a scoped style, the scoped style’s value will apply: src/components/make-it-purple.css ```css h1 { color: purple; } ``` src/components/MyComponent.astro ```astro --- import "./make-it-purple.css" --- ``` If you make the imported style *more specific*, it will have higher precedence over the scoped style: src/components/make-it-purple.css ```css div > h1 { color: purple; } ``` src/components/MyComponent.astro ```astro --- import "./make-it-purple.css" --- ``` ### Import Order [Section titled Import Order](#import-order) When importing multiple stylesheets in an Astro component, the CSS rules are evaluated in the order that they are imported. A higher specificity will always determine which styles to show, no matter when the CSS is evaluated. But, when conflicting styles have the same specificity, the *last one imported* wins: src/components/make-it-purple.css ```css div > h1 { color: purple; } ``` src/components/make-it-green.css ```css div > h1 { color: green; } ``` src/components/MyComponent.astro ```astro --- import "./make-it-green.css" import "./make-it-purple.css" --- ``` While ` ``` ### Link Tags [Section titled Link Tags](#link-tags) Style sheets loaded via [link tags](#load-a-static-stylesheet-via-link-tags) are evaluated in order, before any other styles in an Astro file. Therefore, these styles will have lower precedence than imported stylesheets and scoped styles: src/pages/index.astro ```astro --- import "../components/make-it-purple.css" --- Astro ``` ## CSS Integrations [Section titled CSS Integrations](#css-integrations) Astro comes with support for adding popular CSS libraries, tools, and frameworks to your project like [Tailwind](https://tailwindcss.com) and more! ### Tailwind [Section titled Tailwind](#tailwind) To use Tailwind in your project, install the official [Astro Tailwind integration](/en/guides/integrations-guide/tailwind/) using the `astro add` command for your package manager: * npm ```shell npx astro add tailwind ``` * pnpm ```shell pnpm astro add tailwind ``` * Yarn ```shell yarn astro add tailwind ``` See the [Integrations Guide](/en/guides/integrations-guide/) for instructions on installing, importing and configuring Astro integrations. ## CSS Preprocessors [Section titled CSS Preprocessors](#css-preprocessors) Astro supports CSS preprocessors such as [Sass](https://sass-lang.com/), [Stylus](https://stylus-lang.com/), and [Less](https://lesscss.org/) through [Vite](https://vite.dev/guide/features.html#css-pre-processors). ### Sass and SCSS [Section titled Sass and SCSS](#sass-and-scss) ```shell npm install sass ``` Use ` ``` See [Vite’s docs](https://vite.dev/guide/assets.html#importing-asset-as-string) for full details. ### `?url` CSS Imports [Section titled ?url CSS Imports](#url-css-imports) For advanced use cases, you can import a direct URL reference for a CSS file inside of your project `src/` directory. This can be useful when you need complete control over how a CSS file is loaded on the page. However, this will prevent the optimization of that CSS file with the rest of your page CSS . This is not recommended for most users. Instead, place your CSS files inside of `public/` to get a consistent URL reference. Caution Importing a smaller CSS file with `?url` may return the base64 encoded contents of the CSS file as a data URL in your final build. Either write your code to support encoded data URLs (`data:text/css;base64,...`) or set the [`vite.build.assetsInlineLimit`](https://vite.dev/config/#build-assetsinlinelimit) config option to `0` to disable this feature. src/components/RawStylesUrl.astro ```astro --- // Advanced example! Not recommended for most users. import stylesUrl from '../styles/main.css?url'; --- ``` See [Vite’s docs](https://vite.dev/guide/assets.html#importing-asset-as-url) for full details.
# Syntax Highlighting
> Learn how to highlight your code blocks in Astro.
Astro comes with built-in support for [Shiki](https://shiki.style/) and [Prism](https://prismjs.com/). This provides syntax highlighting for: * all [code fences (\`\`\`)](#markdown-code-blocks) used in a Markdown or MDX file. * content within the [built-in `... ``` If you’re interested in maintaining a Lit integration yourself, you may wish to use the [last published version of `@astrojs/lit`](https://github.com/withastro/astro/tree/astro%404.13.0/packages/integrations/lit) as a starting point and upgrade the relevant packages. Learn more about [Astro’s official integrations](/en/guides/integrations-guide/). ### Removed: `hybrid` rendering mode [Section titled Removed: hybrid rendering mode](#removed-hybrid-rendering-mode) [Implementation PR: Merge output:hybrid and output:static (#11824)](https://github.com/withastro/astro/pull/11824) In Astro v4.x, Astro provided three rendering `output` rendering modes: `'static'`, `'hybrid'`, and `'server'` Astro v5.0 merges the `output: 'hybrid'` and `output: 'static'` configurations into one single configuration (now called `'static'`) that works the same way as the previous hybrid option. It is no longer necessary to specify `output: 'hybrid'` in your Astro config to use server-rendered pages. The new `output: 'static'` has this capability included. Astro will now automatically allow you to opt out of prerendering in your static site with no change to your output configuration required. Any page route or endpoint can include `export const prerender = false` to be server-rendered on demand, while the rest of your site is statically generated. #### What should I do? [Section titled What should I do?](#what-should-i-do-6) If your project used hybrid rendering, you must now remove the `output: 'hybrid'` option from your Astro config as it no longer exists. However, no other changes to your project are required, and you should have no breaking changes. The previous `'hybrid'` behavior is now the default, under a new name `'static'`. astro.config.mjs ```js import { defineConfig } from "astro/config"; export default defineConfig({ output: 'hybrid', }); ``` If you were using the `output: 'static'` (default) option, you can continue to use it as before. By default, all of your pages will continue to be prerendered and you will have a completely static site. You should have no breaking changes to your project. An adapter is still required to deploy an Astro project with any server-rendered pages, no matter which `output` mode your project uses. Failure to include an adapter will result in a warning in development and an error at build time. Learn more about [on-demand rendering in Astro](/en/guides/on-demand-rendering/). ### Removed: Squoosh image service [Section titled Removed: Squoosh image service](#removed-squoosh-image-service) [Implementation PR: remove the squoosh image service (#11770)](https://github.com/withastro/astro/pull/11770) In Astro 4.x, you could configure `image.service: squooshImageService()` to use Squoosh to transform your images instead of Sharp. However, the underlying library `libsquoosh` is no longer maintained and has memory and performance issues. Astro 5.0 removes the Squoosh image optimization service entirely. #### What should I do? [Section titled What should I do?](#what-should-i-do-7) To switch to the built-in Sharp image service, remove the `squooshImageService` import from your Astro config. By default, you will use Sharp for `astro:assets`. astro.config.mjs ```ts import { squooshImageService } from "astro/config"; import { defineConfig } from "astro/config"; export default defineConfig({ image: { service: squooshImageService() } }); ``` If you are using a strict package manager like `pnpm`, you may need to install the `sharp` package manually to use the Sharp image service, even though it is built into Astro by default. If your adapter does not support Astro’s built-in Sharp image optimization, you can [configure a no-op image service](/en/guides/images/#configure-no-op-passthrough-service) to allow you to use the `My site `, if it exists. * The first `<h1>` it finds. * The `pathname` of the page. We strongly recommend you always include a `<title>` in each page for accessibility. ### `prefers-reduced-motion` [Section titled prefers-reduced-motion](#prefers-reduced-motion) Astro’s `<ClientRouter />` component includes a CSS media query that disables *all* view transition animations, including fallback animation, whenever the [`prefer-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) setting is detected. Instead, the browser will simply swap the DOM elements without an animation.
# Upgrade Astro
> Learn how to upgrade Astro
This guide covers how to update your version of Astro and related dependencies, how to learn what has changed from one version to the next, and how to understand Astro’s versioning system and corresponding documentation updates. ## What has changed? [Section titled What has changed?](#what-has-changed) The latest release of Astro is v5.1.10. You can find an exhaustive list of all changes in [Astro’s changelog](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md), and important instructions for upgrading to each new [major version](#major-changes) in our [upgrade guides](#upgrade-guides). ## Upgrade to the latest version [Section titled Upgrade to the latest version](#upgrade-to-the-latest-version) Update your project’s version of Astro and all official integrations to the latest versions with one command using your package manager: * npm ```shell # Upgrade Astro and official integrations together npx @astrojs/upgrade ``` * pnpm ```shell # Upgrade Astro and official integrations together pnpm dlx @astrojs/upgrade ``` * Yarn ```shell # Upgrade Astro and official integrations together yarn dlx @astrojs/upgrade ``` ### Manual Upgrading [Section titled Manual Upgrading](#manual-upgrading) To update Astro and integrations to their current versions manually, use the appropriate command for your package manager. * npm ```shell # Example: upgrade Astro with React and Tailwind integrations npm install astro@latest @astrojs/react@latest @astrojs/tailwind@latest ``` * pnpm ```shell # Example: upgrade Astro with React and Tailwind integrations pnpm add astro@latest @astrojs/react@latest @astrojs/tailwind@latest ``` * Yarn ```shell # Example: upgrade Astro with React and Tailwind integrations yarn add astro@latest @astrojs/react@latest @astrojs/tailwind@latest ``` ### Install a specific version number [Section titled Install a specific version number](#install-a-specific-version-number) To install a specific [version of Astro](https://www.npmjs.com/package/astro?activeTab=versions) or integrations, use the appropriate command for your package manager. * npm ```shell npm install astro@4.5.3 @astrojs/react@3.0.10 ``` * pnpm ```shell pnpm add astro@4.5.3 @astrojs/react@3.0.10 ``` * Yarn ```shell yarn add astro@4.5.3 @astrojs/react@3.0.10 ``` ## Documentation updates [Section titled Documentation updates](#documentation-updates) This documentation is updated for each [minor release](#minor-changes) and [major version release](#major-changes). When new features are added, or existing usage changes, the docs will update to reflect the **current behavior of Astro**. If your project is not updated, then you may notice some behaviors do not match the up-to-date documentation. New features are added to docs with the specific version number in which they were added. This means that if you have not updated to the latest release of Astro, some documented features may be unavailable. Always check the `Added in:` version number and make sure your project is updated before attempting to use new features! If you have not upgraded to the latest major version of Astro, you may encounter significant differences between the Astro documentation and your project’s behavior. We strongly recommend upgrading to the current major version of Astro as soon as you are able. Both the code and the documentation for earlier versions is unsupported. ### Upgrade Guides [Section titled Upgrade Guides](#upgrade-guides) After every [major version release](#major-changes), you will find an **upgrade guide** with information about important changes and instructions for upgrading your project code. The main Astro documentation pages are always **accurate for the latest released version of Astro**. They do not describe or compare to how things worked in previous versions, nor do they highlight updated or changed behavior. See the upgrade guides below for an explanation of changes, comparing the new version to the old. The upgrade guides include everything that could require you to change your own code: breaking changes, deprecations, feature removals and replacements as well as updated usage guidance. Each change to Astro includes a “What should I do?” section to help you successfully update your project code. * [Upgrade to v5](/en/guides/upgrade-to/v5/) * [Upgrade to v4](/en/guides/upgrade-to/v4/) * [Upgrade to v3](/en/guides/upgrade-to/v3/) * [Upgrade to v2](/en/guides/upgrade-to/v2/) * [Upgrade to v1](/en/guides/upgrade-to/v1/) ### Older docs (unmaintained) [Section titled Older docs (unmaintained)](#older-docs-unmaintained) Documentation for older versions of Astro is not maintained, but is available as a static snapshot. Use these versions of docs if you are unable to upgrade your project, but still wish to consult guides and reference: * [unmaintained v4.16.17 snapshot](https://v4.docs.astro.build/en/getting-started/) * [unmaintained v3.6.3 snapshot](https://docs-git-v3-docs-unmaintained-astrodotbuild.vercel.app/) * [unmaintained v2.10.15 snapshot](https://deploy-preview-4405--astro-docs-2.netlify.app/en/getting-started/) ## Semantic versioning [Section titled Semantic versioning](#semantic-versioning) Astro attempts to adhere as much as possible to [semantic versioning](https://semver.org/), which is a set of rules developers use to determine how to assign a version number to a release. Semantic version follows a predictable pattern to inform users of the kind of changes they can expect from one version to the next. Semantic versioning enforces a pattern of `X.Y.Z` for software version numbers. These values represent **major (X)**, **minor (Y)**, and **patch (Z)** updates. ### Patch changes [Section titled Patch changes](#patch-changes) Patch changes are the least disruptive changes. They do not change the way you use Astro, and no change to your own code is required when you update. When Astro issues a “patch” version, the last number increases. (e.g. `astro@4.3.14` -> `astro@4.3.15`) Patches may be released for reasons such as: * Internal changes that do not change Astro’s functionality: * refactors * performance improvements * increase or change in test coverage * aligning with stated documentation and expected behavior * Improvements to logging and error messages. * Re-releases after a failed release. Patch changes also include **most bug fixes**, even in cases where users were taking advantage of existing unintended or undesirable behavior. ### Minor changes [Section titled Minor changes](#minor-changes) Minor releases primarily introduce new features and improvements that you may wish to try, but require no changes to your code. Some existing features may also be **deprecated** (marked for deletion in a future version while continuing to function) in a minor release, giving you the opportunity to prepare for their eventual removal. Minor releases include changes such as: * **Deprecations** of existing features/options with a warning that they will be removed in an upcoming major release. * Introduction of new functionalities. * Introduction of new options in the integration hooks. * Introduction of new functionalities in `astro/app`, notably used for creating new adapters. A minor release may also include smaller, patch changes at the same time. ### Major changes [Section titled Major changes](#major-changes) Major releases will include breaking changes to at least some existing code. These breaking changes are always documented in an [“Upgrade to vX” guide](#upgrade-guides) in Astro. Major releases allow Astro to make significant changes not only to internal logic, but also to intended behavior and usage. Documentation will be updated to reflect the latest version only, and **static, unmaintained snapshots of older docs** are available as a historical record for older projects that are not yet upgraded. Major releases include changes such as: * Removal of previously deprecated functionalities. * Changes of existing functionalities. * Changes of existing options in the integration hooks. * Changes of existing options and functionalities in `astro/app`, notably used for creating new adapters. A major release may also include some non-breaking changes and improvements that would normally be released separately in a minor or patch release. ### Exceptions [Section titled Exceptions](#exceptions) * **Experimental features**. Releasing versions of Astro without adhering to semantic versioning allows Astro developers the greatest flexibility to explore, and even radically change course, during the development of experimental features. Therefore, the behavior of these features can break in minor and patch changes. These features are usually accompanied by an ongoing, public [Request for Consideration (RFC) stage 3](https://github.com/withastro/roadmap#stage-3-rfc--development). It is expected that beta users will follow for updates, and leave early feedback on the discussion to help guide development of these features. Once these features are out of their experimental period, they will follow the normal semantic versioning contract. * **Improvements to the documentation** (e.g. reference and error messages). They are built from source for the `docs` repository. This allows Astro to quickly update docs fixes and improvements in the cases where documentation source content is stored in the main `astro` repository. ### Node.js support and upgrade policies [Section titled Node.js support and upgrade policies](#nodejs-support-and-upgrade-policies) #### Support [Section titled Support](#support) * Astro supports the [**latest *Maintenance* LTS** version of Node.js](https://nodejs.org/en/about/previous-releases#release-schedule). * Astro supports the [**current *Active* LTS** version of Node.js](https://nodejs.org/en/about/previous-releases#release-schedule) * Astro can support odd versions of Node.js. #### Upgrade [Section titled Upgrade](#upgrade) The following rules define when Astro may deprecate, drop, or add support for versions of Node.js: * Odd versions of Node.js can be deprecated and/or dropped when the next even version of Node.js published. This change can occur in a **minor** release of Astro, after a reasonable period of extended support as decided by the Astro Core team. * Upgrading the minimum ***Maintenance* LTS** (within the same major range, e.g. from `v18.14.*` to `v18.20.*`) version of Node.js can occur in a **minor** release of Astro. * Security exception: If a security flaw in Node.js that **affects Astro** is disclosed and fixed, the Core team can bump the minimum version of the ***Maintenance* LTS** in a **patch** release. * Upgrading minor or major versions of Node.js (**not** Maintenance LTS) occurs only in major versions of Astro. * Security exception: If a security flaw in Node.js that **affects Astro** is disclosed and fixed, the Core team can bump the minimum version in a **minor** release. ### Extended maintenance [Section titled Extended maintenance](#extended-maintenance) The Core team will provide extended maintenance **for security fixes only** for one previous major version. This means that if the current major is `v4.*`, the Core team will back port security fixes and issue a new `v3.*` release.
Title
Hello
``` See our [directives reference](/en/reference/directives-reference/#definevars) page to learn more about `define:vars`. ### Passing a `class` to a child component [Section titled Passing a class to a child component](#passing-a-class-to-a-child-component) In Astro, HTML attributes like `class` do not automatically pass through to child components. Instead, accept a `class` prop in the child component and apply it to the root element. When destructuring, you must rename it, because `class` is a [reserved word](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#reserved_words) in JavaScript. Using the default scoped style strategy, you must also pass the `data-astro-cid-*` attribute. You can do this by passing the `...rest` of the props to the component. If you have changed `scopedStyleStrategy` to `'class'` or `'where'`, the `...rest` prop is not necessary. src/components/MyComponent.astro ```astro --- const { class: className, ...rest } = Astro.props; ---My text
My text
``` ## External Styles [Section titled External Styles](#external-styles) There are two ways to resolve external global stylesheets: an ESM import for files located within your project source, and an absolute URL link for files in your `public/` directory, or hosted outside of your project. Read more about using [static assets](/en/guides/imports/) located in `public/` or `src/`. ### Import a local stylesheet [Section titled Import a local stylesheet](#import-a-local-stylesheet) Using an npm package? You may need to update your `astro.config` when importing from npm packages. See the [“import stylesheets from an npm package” section](#import-a-stylesheet-from-an-npm-package) below. You can import stylesheets in your Astro component frontmatter using ESM import syntax. CSS imports work like [any other ESM import in an Astro component](/en/basics/astro-components/#the-component-script), which should be referenced as **relative to the component** and must be written at the **top** of your component script, with any other imports. src/pages/index.astro ```astro --- // Astro will bundle and optimize this CSS for you automatically // This also works for preprocessor files like .scss, .styl, etc. import '../styles/utils.css'; --- ``` CSS `import` via ESM are supported inside of any JavaScript file, including JSX components like React & Preact. This can be useful for writing granular, per-component styles for your React components. ### Import a stylesheet from an npm package [Section titled Import a stylesheet from an npm package](#import-a-stylesheet-from-an-npm-package) You may also need to load stylesheets from an external npm package. This is especially common for utilities like [Open Props](https://open-props.style/). If your package **recommends using a file extension** (i.e. `package-name/styles.css` instead of `package-name/styles`), this should work like any local stylesheet: src/pages/random-page.astro ```astro --- import 'package-name/styles.css'; --- ``` If your package **does *not* suggest using a file extension** (i.e. `package-name/styles`), you’ll need to update your Astro config first! Say you are importing a CSS file from `package-name` called `normalize` (with the file extension omitted). To ensure we can prerender your page correctly, add `package-name` to [the `vite.ssr.noExternal` array](https://vite.dev/config/ssr-options.html#ssr-noexternal): astro.config.mjs ```js import { defineConfig } from 'astro/config'; export default defineConfig({ vite: { ssr: { noExternal: ['package-name'], } } }) ``` Now, you are free to import `package-name/normalize`. This will be bundled and optimized by Astro like any other local stylesheet. src/pages/random-page.astro ```astro --- import 'package-name/normalize'; --- ``` ### Load a static stylesheet via “link” tags [Section titled Load a static stylesheet via “link” tags](#load-a-static-stylesheet-via-link-tags) You can also use the `` element to load a stylesheet on the page. This should be an absolute URL path to a CSS file located in your `/public` directory, or an URL to an external website. Relative `` href values are not supported. src/pages/index.astro ```astro ``` Because this approach uses the `public/` directory, it skips the normal CSS processing, bundling and optimizations that are provided by Astro. If you need these transformations, use the [Import a Stylesheet](#import-a-local-stylesheet) method above. ## Cascading Order [Section titled Cascading Order](#cascading-order) Astro components will sometimes have to evaluate multiple sources of CSS. For example, your component might import a CSS stylesheet, include its own `This header will be purple!
This header will be red!
This header will be red!
This header will be purple!
This header will be purple!
This header will be purple!
This will be purple
will be rendered inline.