This is the abridged developer documentation for Astro # Why Astro? > Astro is the web framework for building content-driven websites like blogs, marketing, and e-commerce. Learn why Astro might be a good choice for your next website. **Astro** is the web framework for building **content-driven websites** like blogs, marketing, and e-commerce. Astro is best-known for pioneering a new [frontend architecture](/en/concepts/islands/) to reduce JavaScript overhead and complexity compared to other frameworks. If you need a website that loads fast and has great SEO, then Astro is for you. ## Features [Section titled “Features”](#features) **Astro is an all-in-one web framework.** It includes everything you need to create a website, built-in. There are also hundreds of different [integrations](https://astro.build/integrations/) and [API hooks](/en/reference/integrations-reference/) available to customize a project to your exact use case and needs. Some highlights include: * **[Islands](/en/concepts/islands/):** A component-based web architecture optimized for content-driven websites. * **[UI-agnostic](/en/guides/framework-components/):** Supports React, Preact, Svelte, Vue, Solid, HTMX, web components, and more. * **[Server-first](/en/guides/on-demand-rendering/):** Moves expensive rendering off of your visitors’ devices. * **[Zero JS, by default](/en/basics/astro-components/):** Less client-side JavaScript to slow your site down. * **[Content collections](/en/guides/content-collections/):** Organize, validate, and provide TypeScript type-safety for your Markdown content. * **[Customizable](/en/guides/integrations-guide/):** Partytown, MDX, and hundreds of integrations to choose from. ## Design Principles [Section titled “Design Principles”](#design-principles) Here are five core design principles to help explain why we built Astro, the problems that it exists to solve, and why Astro may be the best choice for your project or team. Astro is… 1. **[Content-driven](#content-driven):** Astro was designed to showcase your content. 2. **[Server-first](#server-first):** Websites run faster when they render HTML on the server. 3. **[Fast by default](#fast-by-default):** It should be impossible to build a slow website in Astro. 4. **[Easy to use](#easy-to-use):** You don’t need to be an expert to build something with Astro. 5. **[Developer-focused](#developer-focused):** You should have the resources you need to be successful. ### Content-driven [Section titled “Content-driven”](#content-driven) **Astro was designed for building content-rich websites.** This includes marketing sites, publishing sites, documentation sites, blogs, portfolios, landing pages, community sites, and e-commerce sites. If you have content to show, it needs to reach your reader quickly. By contrast, most modern web frameworks were designed for building *web applications*. These frameworks excel at building more complex, application-like experiences in the browser: logged-in admin dashboards, inboxes, social networks, todo lists, and even native-like applications like [Figma](https://figma.com/) and [Ping](https://ping.gg/). However with that complexity, they can struggle to provide great performance when delivering your content. Astro’s focus on content from its beginnings as a static site builder have allowed Astro to **sensibly scale up to performant, powerful, dynamic web applications** that still respect your content and your audience. Astro’s unique focus on content lets Astro make tradeoffs and deliver unmatched performance features that wouldn’t make sense for more application-focused web frameworks to implement. ### Server-first [Section titled “Server-first”](#server-first) **Astro leverages server rendering over client-side rendering in the browser as much as possible.** This is the same approach that traditional server-side frameworks -- PHP, WordPress, Laravel, Ruby on Rails, etc. -- have been using for decades. But you don’t need to learn a second server-side language to unlock it. With Astro, everything is still just HTML, CSS, and JavaScript (or TypeScript, if you prefer). This approach stands in contrast to other modern JavaScript web frameworks like Next.js, SvelteKit, Nuxt, Remix, and others. These frameworks were built for client-side rendering of your entire website and include server-side rendering mainly to address performance concerns. This approach has been dubbed the **Single-Page App (SPA)**, in contrast with Astro’s **Multi-Page App (MPA)** approach. The SPA model has its benefits. However, these come at the expense of additional complexity and performance tradeoffs. These tradeoffs harm page performance -- critical metrics like [Time to Interactive (TTI)](https://web.dev/interactive/) -- which doesn’t make much sense for content-focused websites where first-load performance is essential. Astro’s server-first approach allows you to opt in to client-side rendering only if, and exactly as, necessary. You can choose to add UI framework components that run on the client. You can take advantage of Astro’s view transitions router for finer control over select page transitions and animations. Astro’s server-first rendering, either pre-rendered or on-demand, provides performant defaults that you can enhance and extend. ### Fast by default [Section titled “Fast by default”](#fast-by-default) Good performance is always important, but it is *especially* critical for websites whose success depends on displaying your content. It has been well-proven that poor performance loses you engagement, conversions, and money. For example: * Every 100ms faster → 1% more conversions ([Mobify](https://web.dev/why-speed-matters/), earning +$380,000/yr) * 50% faster → 12% more sales ([AutoAnything](https://www.digitalcommerce360.com/2010/08/19/web-accelerator-revs-conversion-and-sales-autoanything/)) * 20% faster → 10% more conversions ([Furniture Village](https://www.thinkwithgoogle.com/intl/en-gb/marketing-strategies/app-and-mobile/furniture-village-and-greenlight-slash-page-load-times-boosting-user-experience/)) * 40% faster → 15% more sign-ups ([Pinterest](https://medium.com/pinterest-engineering/driving-user-growth-with-performance-improvements-cfc50dafadd7)) * 850ms faster → 7% more conversions ([COOK](https://web.dev/why-speed-matters/)) * Every 1 second slower → 10% fewer users ([BBC](https://www.creativebloq.com/features/how-the-bbc-builds-websites-that-scale)) In many web frameworks, it is easy to build a website that looks great during development only to load painfully slow once deployed. JavaScript is often the culprit, since many phones and lower-powered devices rarely match the speed of a developer’s laptop. Astro’s magic is in how it combines the two values explained above -- a content focus with a server-first architecture -- to make tradeoffs and deliver features that other frameworks cannot. The result is amazing web performance for every website, out of the box. Our goal: **It should be nearly impossible to build a slow website with Astro.** An Astro website can [load 40% faster with 90% less JavaScript](https://twitter.com/t3dotgg/status/1437195415439360003) than the same site built with the most popular React web framework. But don’t take our word for it: watch Astro’s performance leave Ryan Carniato (creator of Solid.js and Marko) [speechless](https://youtu.be/2ZEMb_H-LYE?t=8163). ### Easy to use [Section titled “Easy to use”](#easy-to-use) **Astro’s goal is to be accessible to every web developer.** Astro was designed to feel familiar and approachable regardless of skill level or past experience with web development. The `.astro` UI language is a superset of HTML: any valid HTML is valid Astro templating syntax! So, if you can write HTML, you can write Astro components! But, it also combines some of our favorite features borrowed from other component languages like JSX expressions (React) and CSS scoping by default (Svelte and Vue). This closeness to HTML also makes it easier to use progressive enhancement and common accessibility patterns without any overhead. We then made sure that you could also use your favorite UI component languages that you already know, and even reuse components you might already have. React, Preact, Svelte, Vue, Solid, and others, including web components, are all supported for authoring UI components in an Astro project. Astro was designed to be less complex than other UI frameworks and languages. One big reason for this is that Astro was designed to render on the server, not in the browser. That means that you don’t need to worry about: hooks (React), stale closures (also React), refs (Vue), observables (Svelte), atoms, selectors, reactions, or derivations. There is no reactivity on the server, so all of that complexity melts away. One of our favorite sayings is: **opt in to complexity.** We designed Astro to remove as much “required complexity” as possible from the developer experience, especially as you onboard for the first time. You can build a “Hello World” example website in Astro with just HTML and CSS. Then, when you need to build something more powerful, you can incrementally reach for new features and APIs as you go. ### Developer-focused [Section titled “Developer-focused”](#developer-focused) We strongly believe that Astro is only a successful project if people love using it. Astro has everything you need to support you as you build with Astro. Astro invests in developer tools like a great CLI experience from the moment you open your terminal, an official VS Code extension for syntax highlighting, TypeScript and Intellisense, and documentation actively maintained by hundreds of community contributors and available in 14 languages. Our welcoming, respectful, inclusive community on Discord is ready to provide support, motivation, and encouragement. Open a `#support` thread to get help with your project. Visit our dedicated `#showcase` channel for sharing your Astro sites, blog posts, videos, and even work-in-progress for safe feedback and constructive criticism. Participate in regular live events such as our weekly community call, “Talking and Doc’ing,” and API/bug bashes. As an open-source project, we welcome contributions of all types and sizes from community members of all experience levels. You are invited to join in roadmap discussions to shape the future of Astro, and we hope you’ll contribute fixes and features to the core codebase, compiler, docs, language tools, websites, and other projects. # Islands architecture > Learn about how Astro's islands architecture helps keep sites fast. Astro helped pioneer and popularize a new frontend architecture pattern called **Islands Architecture.** Islands architecture works by rendering the majority of your page to fast, static HTML with smaller “islands” of JavaScript added when interactivity or personalization is needed on the page (an image carousel, for example). This avoids the monolithic JavaScript payloads that slow down the responsiveness of many other, modern JavaScript web frameworks. ## A brief history [Section titled “A brief history”](#a-brief-history) The term “component island” was first coined by Etsy’s frontend architect [Katie Sylor-Miller](https://sylormiller.com/) in 2019. This idea was then expanded on and documented in [this post](https://jasonformat.com/islands-architecture/) by Preact creator Jason Miller on August 11, 2020. > The general idea of an “Islands” architecture is deceptively simple: render HTML pages on the server, and inject placeholders or slots around highly dynamic regions \[…] that can then be “hydrated” on the client into small self-contained widgets, reusing their server-rendered initial HTML.\ > — Jason Miller, Creator of Preact The technique that this architectural pattern builds on is also known as **partial** or **selective hydration.** In contrast, most JavaScript-based web frameworks hydrate & render an entire website as one large JavaScript application (also known as a single-page application, or SPA). SPAs provide simplicity and power but suffer from page-load performance problems due to heavy client-side JavaScript usage. SPAs have their place, even [embedded inside an Astro page](/en/guides/migrate-to-astro/from-create-react-app/). But, SPAs lack the native ability to selectively and strategically hydrate, making them a heavy-handed choice for most projects on the web today. Astro became popular as the first mainstream JavaScript web framework with selective hydration built-in, using that same component islands pattern first coined by Sylor-Miller. We’ve since expanded and evolved on Sylor-Miller’s original work, which helped to inspire a similar component island approach to dynamically server-rendered content. ## What is an island? [Section titled “What is an island?”](#what-is-an-island) In Astro, an island is an enhanced UI component on an otherwise static page of HTML. A [**client island**](#client-islands) is an interactive JavaScript UI component that is hydrated separately from the rest of the page, while a [**server island**](#server-islands) is a UI component that server-renders its dynamic content separately from the rest of the page. Both islands run expensive or slower processes independently, on a per-component basis, for optimized page loads. ## Island components [Section titled “Island components”](#island-components) Astro components are the building blocks of your page template. They render to static HTML with no client-side runtime. Think of a client island as an interactive widget floating in a sea of otherwise static, lightweight, server-rendered HTML. Server islands can be added for personalized or dynamic server-rendered elements, such as a logged in visitor’s profile picture. Header (interactive island) Sidebar (static HTML) Static content like text, images, etc. Image carousel (interactive island) Footer (static HTML) Source: [Islands Architecture: Jason Miller](https://jasonformat.com/islands-architecture/) An island always runs in isolation from other islands on the page, and multiple islands can exist on a page. Client islands can still share state and communicate with each other, even though they run in different component contexts. This flexibility allows Astro to support multiple UI frameworks like [React](https://react.dev/), [Preact](https://preactjs.com/), [Svelte](https://svelte.dev/), [Vue](https://vuejs.org/), and [SolidJS](https://www.solidjs.com/). Because they are independent, you can even mix several frameworks on each page. ## Client Islands [Section titled “Client Islands”](#client-islands) By default, Astro will automatically render every UI component to just HTML & CSS, **stripping out all client-side JavaScript automatically.** src/pages/index.astro ```astro ``` This may sound strict, but this behavior is what keeps Astro websites fast by default and protects developers from accidentally sending unnecessary or unwanted JavaScript that might slow down their website. Turning any static UI component into an interactive island requires only a `client:*` directive. Astro then automatically builds and bundles your client-side JavaScript for optimized performance. src/pages/index.astro ```astro ``` With islands, client-side JavaScript is only loaded for the explicit interactive components that you mark using `client:*` directives. And because interaction is configured at the component-level, you can handle different loading priorities for each component based on its usage. For example, `client:idle` tells a component to load when the browser becomes idle, and `client:visible` tells a component to load only once it enters the viewport. ### Benefits of client islands The most obvious benefit of building with Astro Islands is performance: the majority of your website is converted to fast, static HTML and JavaScript is only loaded for the individual components that need it. JavaScript is one of the slowest assets that you can load per-byte, so every byte counts. Another benefit is parallel loading. In the example illustration above, the low-priority “image carousel” island doesn’t need to block the high-priority “header” island. The two load in parallel and hydrate in isolation, meaning that the header becomes interactive immediately without having to wait for the heavier carousel lower down the page. Even better, you can tell Astro exactly how and when to render each component. If that image carousel is really expensive to load, you can attach a special [client directive](/en/reference/directives-reference/#client-directives) that tells Astro to only load the carousel when it becomes visible on the page. If the user never sees it, it never loads. In Astro, it’s up to you as the developer to explicitly tell Astro which components on the page need to also run in the browser. Astro will only hydrate exactly what’s needed on the page and leave the rest of your site as static HTML. **Client islands are the secret to Astro’s fast-by-default performance story!** Read more about [using JavaScript framework components](/en/guides/framework-components/) in your project. ## Server islands [Section titled “Server islands”](#server-islands) Server islands are a way to move expensive or slow server-side code out of the way of the main rendering process, making it easy to combine high-performance static HTML and dynamic server-generated components. Add the [`server:defer` directive](/en/reference/directives-reference/#server-directives) to any Astro component on your page to turn it into its own server island: src/pages/index.astro ```astro --- import Avatar from "../components/Avatar.astro"; --- ``` This breaks up your page with smaller areas of server-rendered content that each load in parallel. Your page’s main content can be rendered immediately with placeholder content, such as a generic avatar until your island’s own content is available. With server islands, having small components of personalized content does not delay the rendering of an otherwise static page. This rendering pattern was built to be portable. It does not depend on any server infrastructure so it will work with any host, from a Node.js server in a Docker container to the serverless provider of your choice. ### Benefits of server islands One benefit of server islands is the ability to render the more highly dynamic parts of your page on the fly. This allows the outer shell and main content to be more aggressively cached, providing faster performance. Another benefit is providing a great visitor experience. Server islands are optimized and load quickly, often even before the browser has even painted the page. But in the short time it takes for your islands to render, you can display custom fallback content and prevent any layout shift. An example of a site that benefits from Astro’s server islands is an e-commerce storefront. Although the main content of product pages change infrequently, these pages typically have some dynamic pieces: * The user’s avatar in the header. * Special deals and sales for the product. * User reviews. Using server islands for these elements, your visitor will see the most important part of the page, your product, immediately. Generic avatars, loading spinners, and store announcements can be displayed as fallback content until the personalized parts are available. Read more about [using server islands](/en/guides/server-islands/) in your project. # Install Astro > How to install Astro and start a new project. The [`create astro` CLI command](#install-from-the-cli-wizard) is the fastest way to start a new Astro project from scratch. It will walk you through every step of setting up your new Astro project and allow you to choose from a few different official starter templates. You can also run the CLI command with the `template` flag to begin your project using any existing theme or starter template. Explore our [themes and starters showcase](https://astro.build/themes/) where you can browse themes for blogs, portfolios, documentation sites, landing pages, and more! To install Astro manually instead, see our [step-by-step manual installation guide](#manual-setup). ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **Node.js** - `v18.20.8` or `v20.3.0`, `v22.0.0` or higher. ( `v19` and `v21` are not supported.) * **Text editor** - We recommend [VS Code](https://code.visualstudio.com/) with our [Official Astro extension](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode). * **Terminal** - Astro is accessed through its command-line interface (CLI). ## Browser compatibility [Section titled “Browser compatibility”](#browser-compatibility) Astro is built with Vite which targets browsers with modern JavaScript support by default. For a complete reference, you can see the [list of currently supported browser versions in Vite](https://vite.dev/guide/build.html#browser-compatibility). ## Install from the CLI wizard [Section titled “Install from the CLI wizard”](#install-from-the-cli-wizard) You can run `create astro` anywhere on your machine, so there’s no need to create a new empty directory for your project before you begin. If you don’t have an empty directory yet for your new project, the wizard will help create one for you automatically. 1. Run the following command in your terminal to start the install wizard: * npm ```shell # create a new project with npm npm create astro@latest ``` * pnpm ```shell # create a new project with pnpm pnpm create astro@latest ``` * Yarn ```shell # create a new project with yarn yarn create astro ``` If all goes well, you will see a success message followed by some recommended next steps. 2. Now that your project has been created, you can `cd` into your new project directory to begin using Astro. 3. If you skipped the “Install dependencies?” step during the CLI wizard, then be sure to install your dependencies before continuing. * npm ```shell npm install ``` * pnpm ```shell pnpm install ``` * Yarn ```shell yarn install ``` 4. 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! ## CLI installation flags [Section titled “CLI installation flags”](#cli-installation-flags) You can run the `create astro` command with additional flags to customize the setup process (e.g. answering “yes” to all questions, skipping the Houston animation) or your new project (e.g. install git or not, add integrations). See [all the available `create astro` command flags](https://github.com/withastro/astro/blob/main/packages/create-astro/README.md) ### Add integrations [Section titled “Add integrations”](#add-integrations) You can start a new Astro project and install any [official integrations](/en/guides/integrations-guide/) or community integrations that support the `astro add` command at the same time by passing the `--add` argument to the `create astro` command. Run the following command in your terminal, substituting any integration that supports the `astro add` command: * npm ```shell # create a new project with React and Partytown npm create astro@latest -- --add react --add partytown ``` * pnpm ```shell # create a new project with React and Partytown pnpm create astro@latest --add react --add partytown ``` * Yarn ```shell # create a new project with React and Partytown yarn create astro --add react --add partytown ``` ### Use a theme or starter template [Section titled “Use a theme or starter template”](#use-a-theme-or-starter-template) You can start a new Astro project based on an [official example](https://github.com/withastro/astro/tree/main/examples) or the `main` branch of any GitHub repository by passing a `--template` argument to the `create astro` command. Run the following command in your terminal, substituting the official Astro starter template name, or the GitHub username and repository of the theme you want to use: * npm ```shell # create a new project with an official example npm create astro@latest -- --template # create a new project based on a GitHub repository’s main branch npm create astro@latest -- --template / ``` * pnpm ```shell # create a new project with an official example pnpm create astro@latest --template # create a new project based on a GitHub repository’s main branch pnpm create astro@latest --template / ``` * Yarn ```shell # create a new project with an official example yarn create astro --template # create a new project based on a GitHub repository’s main branch yarn create astro --template / ``` By default, this command will use the template repository’s `main` branch. To use a different branch name, pass it as part of the `--template` argument: `/#`. ## Manual Setup [Section titled “Manual Setup”](#manual-setup) This guide will walk you through the steps to manually install and configure a new Astro project. If you prefer not to use our automatic `create astro` CLI tool, you can set up your project yourself by following the guide below. 1. Create your directory Create an empty directory with the name of your project, and then navigate into it. ```bash mkdir my-astro-project cd my-astro-project ``` Once you are in your new directory, create your project `package.json` file. This is how you will manage your project dependencies, including Astro. If you aren’t familiar with this file format, run the following command to create one. * npm ```shell npm init --yes ``` * pnpm ```shell pnpm init ``` * Yarn ```shell yarn init --yes ``` 2. Install Astro First, install the Astro project dependencies inside your project. * npm ```shell npm install astro ``` * pnpm ```shell pnpm add astro ``` * Yarn ```shell yarn add astro ``` Then, replace any placeholder “scripts” section of your `package.json` with the following: package.json ```diff { "scripts": { -"test": "echo \"Error: no test specified\" && exit 1", +"dev": "astro dev", +"build": "astro build", +"preview": "astro preview" }, } ``` You’ll use these scripts later in the guide to start Astro and run its different commands. 3. Create your first page In your text editor, create a new file in your directory at `src/pages/index.astro`. This will be your first Astro page in the project. For this guide, copy and paste the following code snippet (including `---` dashes) into your new file: src/pages/index.astro ```astro --- // Welcome to Astro! Everything between these triple-dash code fences // is your "component frontmatter". It never runs in the browser. console.log('This runs in your terminal, not the browser!'); ---

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 MDX 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 on . Visit that link in your browser and see your new site! ### Work in development mode [Section titled “Work in development mode”](#work-in-development-mode) Astro will listen for live file changes in your `src/` directory and update your site preview as you build, so you will not need to restart the server as you make changes during development. You will always be able to see an up-to-date version of your site in your browser when the dev server is running. When viewing your site in the browser, you’ll have access to the [Astro dev toolbar](/en/guides/dev-toolbar/). As you build, it will help you inspect your [islands](/en/concepts/islands/), spot accessibility issues, and more. If you aren’t able to open your project in the browser after starting the dev server, go back to the terminal where you ran the `dev` command and check the message displayed. It should tell you if an error occurred, or if your project is being served at a different URL than . ## Build and preview your site [Section titled “Build and preview your site”](#build-and-preview-your-site) To check the version of your site that will be created at build time, quit the dev server (`Ctrl` + `C`) and run the appropriate build command for your package manager in your terminal: * npm ```shell npm run build ``` * pnpm ```shell pnpm build ``` * yarn ```shell yarn run build ``` Astro will build a deploy-ready version of your site in a separate folder (`dist/` by default) and you can watch its progress in the terminal. This will alert you to any build errors in your project before you deploy to production. If TypeScript is configured to `strict` or `strictest`, the `build` script will also check your project for type errors. When the build is finished, run the appropriate `preview` command (e.g. `npm run preview`) in your terminal and you can view the built version of your site locally in the same browser preview window. Note that this previews your code as it existed when the build command was last run. This is meant to give you a preview of how your site will look when it is deployed to the web. Any later changes you make to your code after building will **not** be reflected while you preview your site until you run the build command again. Use (`Ctrl` + `C`) to quit the preview and run another terminal command, such as restarting the dev server to go back to [working in development mode](#work-in-development-mode) which does update as you edit to show a live preview of your code changes. Read more about [the Astro CLI](/en/reference/cli-reference/) and the terminal commands you will use as you build with Astro. ## Next Steps [Section titled “Next Steps”](#next-steps) Success! You are now ready to start building with Astro! 🥳 Here are a few things that we recommend exploring next. You can read them in any order. You can even leave our documentation for a bit and go play in your new Astro project codebase, coming back here whenever you run into trouble or have a question. ### Configure your dev environment [Section titled “Configure your dev environment”](#configure-your-dev-environment) Explore the guides below to customize your development experience. [Editor Setup ](/en/editor-setup/)Customize your code editor to improve the Astro developer experience and unlock new features. [Dev Toolbar ](/en/guides/dev-toolbar/)Explore the helpful features of the dev toolbar. [TypeScript Configuration ](/en/guides/typescript/)Configure options for type-checking, IntelliSense, and more. ### Explore Astro’s Features [Section titled “Explore Astro’s Features”](#explore-astros-features) [Understand your codebase ](/en/basics/project-structure/)Learn about Astro’s file structure in our Project Structure guide. [Create content collections ](/en/guides/content-collections/)Add content to your new site with frontmatter validation and automatic type-safety. [Add view transitions ](/en/guides/view-transitions/)Create seamless page transitions and animations. [Learn about Islands ](/en/concepts/islands/)Read about Astro's islands architecture. ### Take the introductory tutorial [Section titled “Take the introductory tutorial”](#take-the-introductory-tutorial) Build a fully functional Astro blog starting from a single blank page in our [introductory tutorial](/en/tutorial/0-introduction/). This is a great way to see how Astro works and walks you through the basics of pages, layouts, components, routing, islands, and more. It also includes an optional, beginner-friendly unit for those newer to web development concepts in general, which will guide you through installing the necessary applications on your computer, creating a GitHub account, and deploying your site. # Configuration overview > Get to know the ways you can configure and customize your new project and your development experience. Astro is a flexible, unopinionated framework that allows you to configure your project in many different ways. This means that getting started with a new project might feel overwhelming: there is no “one best way” to set up your Astro project! The guides in this “Configuration” section will help you familiarize yourself with the various files that allow you to configure and customize aspects of your project and development environment. If this is your first Astro project, or if it’s been a while since you’ve set up a new project, use the following guides and reference in the documentation for assistance. ## The Astro config File [Section titled “The Astro config File”](#the-astro-config-file) The [Astro config file](/en/reference/configuration-reference/) is a JavaScript file included at the root of every starter project: astro.config.mjs ```js import { defineConfig } from "astro/config"; export default defineConfig({ // your configuration options here... }); ``` It is only required if you have something to configure, but most projects will use this file. The `defineConfig()` helper provides automatic IntelliSense in your IDE and is where you will add all your configuration options to tell Astro how to build and render your project to HTML. We recommend using the default file format `.mjs` in most cases, or `.ts` if you want to write TypeScript in your config file. However, `astro.config.js` and `astro.config.cjs` are also supported. Read Astro’s [configuration reference](/en/reference/configuration-reference/) for a full overview of all supported configuration options. ## The TypeScript config File [Section titled “The TypeScript config File”](#the-typescript-config-file) Every Astro starter project includes a `tsconfig.json` file in your project. Astro’s [component script](/en/basics/astro-components/#the-component-script) is Typescript, which provides Astro’s editor tooling and allows you to optionally add syntax to your JavaScript for type checking of your own project code. Use the `tsconfig.json` file to configure the TypeScript template that will perform type checks on your code, configure TypeScript plugins, set import aliases, and more. Read Astro’s [TypeScript guide](/en/guides/typescript/) for a full overview of TypeScript options and Astro’s built-in utility types. ## Development Experience [Section titled “Development Experience”](#development-experience) While you work in development mode, you can take advantage of your code editor and other tools to improve the Astro developer experience. Astro provides its own official VS Code extension and is compatible with several other popular editor tools. Astro also provides a customizable toolbar that displays in your browser preview while the dev server is running. You can install and even build your own toolbar apps for additional functionality. Read Astro’s guides to [editor setup options](/en/editor-setup/) and [using the dev toolbar](/en/guides/dev-toolbar/) to learn how to customize your development experience. ## Common new project tasks [Section titled “Common new project tasks”](#common-new-project-tasks) Here are some first steps you might choose to take with a new Astro project. ### Add your deployment domain [Section titled “Add your deployment domain”](#add-your-deployment-domain) For generating your sitemap and creating canonical URLs, configure your deployment URL in the [`site`](/en/reference/configuration-reference/#site) option. If you are deploying to a path (e.g. `www.example.com/docs`), you can also configure a [`base`](/en/reference/configuration-reference/#base) for the root of your project. Additionally, different deployment hosts may have different behavior regarding trailing slashes at the end of your URLs. (e.g. `example.com/about` vs `example.com/about/`). Once your site is deployed, you may need to configure your [`trailingSlash`](/en/reference/configuration-reference/#trailingslash) preference. astro.config.mjs ```js import { defineConfig } from "astro/config"; export default defineConfig({ site: "https://www.example.com", base: "/docs", trailingSlash: "always", }); ``` ### Add site metadata [Section titled “Add site metadata”](#add-site-metadata) Astro does not use its configuration file for common SEO or meta data, only for information required to build your project code and render it to HTML. Instead, this information is added to your page `` using standard HTML `` and `` tags, just as if you were writing plain HTML pages. One common pattern for Astro sites is to create a `` [`.astro` component](/en/basics/astro-components/) that can be added to a common [layout component](/en/basics/layouts/) so it can apply to all your pages. src/components/MainLayout.astro ```astro --- import Head from "./Head.astro"; const { ...props } = Astro.props; --- ``` Because `Head.astro` is just a regular Astro component, you can import files and receive props passed from other components, such as a specific page title. src/components/Head.astro ```astro --- import Favicon from "../assets/Favicon.astro"; import SomeOtherTags from "./SomeOtherTags.astro"; const { title = "My Astro Website", ...props } = Astro.props; --- {title} ``` # Astro Courses > Learn Astro with out-of-this-world courses and tutorials. Want to get started learning Astro with a course or tutorial? You can learn the basics of Astro with our [official docs Build a Blog tutorial](/en/tutorial/0-introduction/), or explore our collection of recommended Astro educational content. ## Education Partners [Section titled “Education Partners”](#education-partners) Learn Astro from trusted Astro educators, with video lessons, interactive challenges, and projects! [Learn Astro with Coding in Public ](https://learnastro.dev/?code=ASTRO_PROMO)A premium interactive course with 150+ video lessons that teaches you how to use Astro’s built-in tooling and features. [Learn Astro with James Q Quick ](https://scrimba.com/intro-to-astro-c00ar0fi5u?via=astro)Build your first Astro site with 35 interactive Scrimba lessons, with video and IDE merged into one unique learning platform. ## Community learning resources [Section titled “Community learning resources”](#community-learning-resources) Learn from your fellow astronauts with curated collections of guides, articles, and blog posts. [Astro Tips ](https://astro-tips.dev/)Advanced, unusual, experimental, and community-written recipes, tutorials, and quick tips. [Astro Support Squid ](https://get.supportsquid.ink/)An open, public Astro support forum and knowledge base outside of the Astro Discord. # Components > An introduction to Astro components. **Astro components** are the basic building blocks of any Astro project. They are HTML-only templating components with no client-side runtime and use the `.astro` file extension. Astro components are extremely flexible. An Astro component can be as small as a snippet of HTML, like a collection of common `` tags that make SEO easy to work with. Components can be reusable UI elements, like a header or a profile card. Astro components can even contain an entire page layout or, when located in the special `src/pages/` folder, be an entire page itself. The most important thing to know about Astro components is that they **don’t render on the client**. They render to HTML either at build-time or on-demand. You can include JavaScript code inside of your component frontmatter, and all of it will be stripped from the final page sent to your users’ browsers. The result is a faster site, with zero JavaScript footprint added by default. When your Astro component does need client-side interactivity, you can add [standard HTML `
Target here
``` The `.astro` partial must exist at the corresponding file path, and include an export defining the page as a partial: src/pages/partials/clicked.astro ```astro --- export const partial = true; ---
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 [**``**](/en/basics/astro-components/#slots) to specify where individual page content should be injected. But, there is nothing special about a layout component! They can [accept props](/en/basics/astro-components/#component-props) and [import and use other components](/en/basics/astro-components/#component-structure) like any other Astro component. They can include [UI frameworks components](/en/guides/framework-components/) and [client-side scripts](/en/guides/client-side-scripts/). They do not even have to provide a full page shell, and can instead be used as partial UI templates. However, if a layout component does contain a page shell, its `` element must be the parent of all other elements in the component. Layout components are commonly placed in a `src/layouts` directory in your project for organization, but this is not a requirement; you can choose to place them anywhere in your project. You can even colocate layout components alongside your pages by [prefixing the layout names with `_`](/en/guides/routing/#excluding-pages). ## Sample Layout [Section titled “Sample Layout”](#sample-layout) src/layouts/MySiteLayout.astro ```astro --- import BaseHead from '../components/BaseHead.astro'; import Footer from '../components/Footer.astro'; const { title } = Astro.props; ---

{title}