Skip to content

Latest commit

 

History

History
222 lines (158 loc) · 7.63 KB

README.md

File metadata and controls

222 lines (158 loc) · 7.63 KB
Raw

Astro

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

# 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:

{
  "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:

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: '',
  /** Options specific to `astro build` */
  buildOptions: {
    /** Generate sitemap (set to "false" to disable) */
    sitemap: true,
  },
  /** Options for the development server run with `astro dev`. */
  devOptions: {
    /** The port to run the dev server on. */
    port: 3000
  }
};

🥾 Guides

🚀 Basic Usage

Even though nearly-everything is configurable, we recommend starting out by creating an astro/ folder in your project with the following structure:

├── astro/
│   ├── components/
│   └── pages/
│       └── index.astro
├── public/
└── package.json
  • astro/components/*: where your reusable components go. You can place these anywhere, but we recommend a single folder to keep them organized.
  • astro/pages/*: this is a special folder where your routing lives.

🚦 Routing

Routing happens in astro/pages/*. Every .astro or .md.astro file in this folder corresponds with a public URL. For example:

Local file Public URL
astro/pages/index.astro /index.html
astro/pages/post/my-blog-post.md.astro /post/my-blog-post/index.html

🗂 Static Assets

Static assets should be placed in a public/ folder in your project. You can place any images, fonts, files, or global CSS in here you need to reference.

🪨 Generating HTML with Astro

TODO: Astro syntax guide

⚡ Dynamic Components

TODO: Astro dynamic components guide

💧 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.

  • <MyComponent /> will render an HTML-only version of MyComponent (default)
  • <MyComponent:load /> will render MyComponent on page load
  • <MyComponent:idle /> will use requestIdleCallback() to render MyComponent as soon as main thread is free
  • <MyComponent:visible /> will use an IntersectionObserver 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 <Provider> wrapper to every component island. Planned.)
    • Recoil: Full Support
  • Svelte
    • 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)

To learn more about writing styles in Astro, see our Styling Guide.

👉 Styling

🐶 Fetching Data

Fetching data is what Astro is all about! Whether your data lives remotely in an API or in your local project, Astro has got you covered.

For fetching from a remote API, use a native JavaScript fetch() (docs) as you are used to. For fetching local content, use Astro.fetchContent() (docs).

// astro/components/MyComponent.Astro

---
// Example 1: fetch remote data from your own API
const remoteData = await fetch('https://api.mysite.com/v1/people').then((res) => res.json());

// Example 2: load local markdown files
const localData = Astro.fetchContent('../post/*.md');
---

🗺️ Sitemap

Astro will automatically create a /sitemap.xml for you for SEO! Be sure to set the site URL in your Astro config so the URLs can be generated properly.

⚠️ Note that Astro won’t inject this into your HTML for you! You’ll have to add the tag yourself in your <head> on all pages that need it:

<link rel="sitemap" href="/sitemap.xml" />
Examples

🍱 Collections (beta)

Fetching data is easy in Astro. But what if you wanted to make a paginated blog? What if you wanted an easy way to sort data, or filter, say, by a given tag? When you need something a little more powerful than simple data fetching, Astro’s Collections API may be what you need.

👉 Collections API

🚀 Build & Deployment

Add a build npm script to your /package.json file:

{
  "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

👉 Full API Reference