![Astro](./assets/social/banner.png) **Astro** is a next-generation static-site generator with partial hydration. Use your favorite JS framework and ship bare-minimum JS (or none at all!). ## 🔧 Setup ```bash # currently hidden during private beta, please don't share :) npm install astro@shhhhh # NOTE: There is currently a bug in Snowpack that prevents you # from using astro outside of the monorepo setup that we have here. # For now, do all development inside the `examples/` directory for this repo. ``` ## 🧞 Development Add a `dev` npm script to your `/package.json` file: ```json { "scripts": { "dev": "astro dev ." } } ``` Then run: ``` npm run dev ``` ### ⚙️ Configuration To configure Astro, add a `astro.config.mjs` file in the root of your project. All settings are optional. Here are the defaults: ```js export default { /** Where to resolve all URLs relative to. Useful if you have a monorepo project. */ projectRoot: '.', /** Path to Astro components, pages, and data */ astroRoot: './astro', /** When running `astro build`, path to final static output */ dist: './_site', /** A folder of static files Astro will copy to the root. Useful for favicons, images, and other files that don’t need processing. */ public: './public', /** Extension-specific handlings */ extensions: { /** Set this to "preact" or "react" to determine what *.jsx files should load */ '.jsx': 'react', }, /** Your public domain, e.g.: https://my-site.dev/ */ site: '', }; ``` ### 💧 Partial Hydration By default, Astro outputs zero client-side JS. If you'd like to include an interactive component in the client output, you may use any of the following techniques. - `` will render an HTML-only version of `MyComponent` (default) - `` will render `MyComponent` on page load - `` will use [requestIdleCallback()][request-idle-cb] to render `MyComponent` as soon as main thread is free - `` will use an [IntersectionObserver][intersection-observer] to render `MyComponent` when the element enters the viewport ### ⚛️ State Management Frontend state management depends on your framework of choice. Below is a list of popular frontend state management libraries, and their current support with Astro. Our goal is to support all popular state management libraries, as long as there is no technical reason that we cannot. - **React/Preact** - [ ] **Redux: Partial Support** (Note: You can access a Redux store directly, but full `react-redux` support requires the ability to set a custom `` wrapper to every component island. Planned.) - [x] **Recoil: Full Support** - **Svelte** - [x] **Svelte Stores: Full Support** - **Vue:** - [ ] **Vuex: Partial Support** (Note: You can access a vuex store directly, but full `vuex` support requires the ability to set a custom `vue.use(store)` call to every component island. Planned.) _Are we missing your favorite state management library? Add it to the list above in a PR (or create an issue)!_ ### 💅 Styling Styling in Astro is meant to be as flexible as you’d like it to be! The following options are all supported: | Framework | Global CSS | Scoped CSS | CSS Modules | | :--------------- | :--------: | :--------: | :---------: | | Astro (`.astro`) | ✅ | ✅ | N/A¹ | | React / Preact | ✅ | ❌ | ✅ | | Vue | ✅ | ✅ | ✅ | | Svelte | ✅ | ✅ | ❌ | ¹ _`.astro` files have no runtime, therefore Scoped CSS takes the place of CSS Modules (styles are still scoped to components, but don’t need dynamic values)_ #### 🖍 Styling by Framework ##### Astro Styling in an Astro component is done by adding a `
I’m a scoped style and only apply to this component

I have both scoped and global styles

``` **Tips** - ` ``` You should see Tailwind styles compile successfully in Astro. 💁 **Tip**: to reduce duplication, try loading `@tailwind base` from a parent page (`./pages/*.astro`) instead of the component itself. ## 🚀 Build & Deployment Add a `build` npm script to your `/package.json` file: ```json { "scripts": { "dev": "astro dev .", "build": "astro build ." } } ``` Then run: ``` npm run build ``` Now upload the contents of `/_site_` to your favorite static site host. ## 📚 API ### `Astro` global The `Astro` global is available in all contexts in `.astro` files. It has the following functions: #### `config` `Astro.config` returns an object with the following properties: | Name | Type | Description | | :----- | :------- | :--------------------------------------------------------------------------------------------------------- | | `site` | `string` | Your website’s public root domain. Set it with `site: "https://mysite.com"` in your [Astro config][config] | #### `fetchContent()` `Astro.fetchContent()` is a way to load local `*.md` files into your static site setup. You can either use this on its own, or within [Astro Collections][collections]. ``` // ./astro/components/my-component.astro --- const data = Astro.fetchContent('../pages/post/*.md'); // returns an array of posts that live at ./astro/pages/post/*.md ---
{data.slice(0, 3).map((post) => ( ))}
``` `.fetchContent()` only takes one parameter: a relative URL glob of which local files you’d like to import. Currently only `*.md` files are supported. It’s synchronous, and returns an array of items of type: ``` { url: string; // the URL of this item (if it’s in pages/) content: string; // the HTML of this item // frontmatter data expanded here }[]; ``` [autoprefixer]: https://github.com/postcss/autoprefixer [browserslist]: https://github.com/browserslist/browserslist [collections]: #-collections-beta [css-modules]: https://github.com/css-modules/css-modules [config]: #%EF%B8%8F-configuration [fetch-content]: #fetchContent-- [intersection-observer]: https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API [request-idle-cb]: https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback [sass]: https://sass-lang.com/ [sass-use]: https://sass-lang.com/documentation/at-rules/use [svelte]: https://svelte.dev [svelte-style]: https://svelte.dev/docs#style [tailwind]: https://tailwindcss.com [tailwind-utilities]: https://tailwindcss.com/docs/adding-new-utilities#using-css [vue-css-modules]: https://vue-loader.vuejs.org/guide/css-modules.html [vue-scoped]: https://vue-loader.vuejs.org/guide/scoped-css.html