diff options
Diffstat (limited to 'docs/guides')
| -rw-r--r-- | docs/guides/data-fetching.md | 33 | ||||
| -rw-r--r-- | docs/guides/deploy.md | 44 | ||||
| -rw-r--r-- | docs/guides/imports.md | 10 | ||||
| -rw-r--r-- | docs/guides/markdown-content.md | 2 | ||||
| -rw-r--r-- | docs/guides/publish-to-npm.md | 10 | ||||
| -rw-r--r-- | docs/guides/styling.md | 41 |
6 files changed, 80 insertions, 60 deletions
diff --git a/docs/guides/data-fetching.md b/docs/guides/data-fetching.md index 44c25f90e..8d9ff143b 100644 --- a/docs/guides/data-fetching.md +++ b/docs/guides/data-fetching.md @@ -3,24 +3,27 @@ layout: ~/layouts/Main.astro title: Data Fetching --- -Astro support `fetch()` and "top-level await" to help you do remote data fetching inside of your page. See the ["Data Loading" Pages section](/docs/core-concepts/astro-pages.md#data-loading) for more info. +Astro components and pages can fetch remote data to help generate your pages. Astro provides two different tools to pages to help you do this: **fetch()** and **top-level await.** -**Important:** These are not yet available inside of non-page Astro components. Instead, do all of your data loading inside of your pages, and then pass them to your components as props. +### `fetch()` + +Astro pages have access to the global `fetch()` function in their setup script. `fetch()` is a native JavaScript API ([MDN](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch)) that lets you make HTTP requests for things like APIs and resources. + +Even though Astro component scripts run inside of Node.js (and not in the browser) Astro provides this native API so that you can fetch data at page build time. -## Example ```astro -// Example: src/pages/foo.astro -// top-level `fetch()` and `await` are both supported natively in Astro (pages only). -const allPokemonResponse = await fetch(`https://pokeapi.co/api/v2/pokemon?limit=150`); -const allPokemonResult = await allPokemonResponse.json(); -const allPokemon = allPokemonResult.results; --- -<html lang="en"> - <head> - <title>Original 150 Pokemon</head> - <body> - {allPokemon.map((pokemon) => (<h1>{pokemon.name}</h1>))} - </body> -</html> +const response = await fetch('http://example.com/movies.json'); +const data = await response.json(); +// Remember: Astro component scripts log to the CLI +console.log(data); +--- +<!-- Output the result to the page --> +<div>{JSON.stringify(data)}</div> ``` +### Top-level await + +`await` is another native JavaScript feature that lets you await the response of some asynchronous promise ([MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await)). Astro supports `await` in the top-level of your component script. + +**Important:** These are not yet available inside of non-page Astro components. Instead, do all of your data loading inside of your pages, and then pass them to your components as props. diff --git a/docs/guides/deploy.md b/docs/guides/deploy.md index df0cf1432..9bca1d56d 100644 --- a/docs/guides/deploy.md +++ b/docs/guides/deploy.md @@ -1,25 +1,27 @@ --- layout: ~/layouts/Main.astro -title: Deploy Your Website +title: Deploy a Website --- > This page is based off of [Vite's](https://vitejs.dev/) well-documented [static deploy instructions](https://vitejs.dev/guide/static-deploy.html). The following guides are based on some shared assumptions: -- You are using the default build output location (`dist/`). This location [can be changed using the `dist` configuration option](/docs/reference/configuration-reference.md). +- You are using the default build output location (`dist/`). This location [can be changed using the `dist` configuration option](/reference/configuration-reference). - You are using npm. You can use equivalent commands to run the scripts if you are using Yarn or other package managers. - Astro is installed as a local dev dependency in your project, and you have setup the following npm scripts: ```json { "scripts": { - "build": "astro build", - "preview": "astro preview" + "start": "astro dev", + "build": "astro build" } } ``` + + ## Building The App You may run `npm run build` command to build the app. @@ -33,7 +35,8 @@ By default, the build output will be placed at `dist/`. You may deploy this `dis ## GitHub Pages 1. Set the correct `buildOptions.site` in `astro.config.js`. -2. Inside your project, create `deploy.sh` with the following content (with highlighted lines uncommented appropriately), and run it to deploy: +2. Run `touch public/.nojekyll` to create a `.nojekyll` file in `public/`. This [bypasses GitHub Page's default behavior](https://github.blog/2009-12-29-bypassing-jekyll-on-github-pages/) to ignore paths prefixed with `_`. +3. Inside your project, create `deploy.sh` with the following content (uncommenting the appropriate lines), and run it to deploy: ```bash{13,20,23} #!/usr/bin/env sh @@ -55,15 +58,14 @@ By default, the build output will be placed at `dist/`. You may deploy this `dis git commit -m 'deploy' # if you are deploying to https://<USERNAME>.github.io - # git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master + # git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git main # if you are deploying to https://<USERNAME>.github.io/<REPO> - # git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages + # git push -f git@github.com:<USERNAME>/<REPO>.git main:gh-pages cd - ``` - - > You can also run the above script in your CI setup to enable automatic deployment on each push. +> You can also run the above script in your CI setup to enable automatic deployment on each push. ### GitHub Actions @@ -120,12 +122,26 @@ TODO: We'd love an example action snippet to share here! ## Netlify -1. On [Netlify](https://netlify.com), setup up a new project from GitHub with the following settings: +In your codebase, make sure you have a `.nvmrc` file with `v14.15.1` in it. + +You can configure your deploy in two ways, via the Netlify website or with the `netlify.toml` file. + +With the `netlify.toml` file, add it at the top level of your project with the following settings: + +```toml +[build] + command = "npm run build" + publish = "dist" +``` + +Then, set up a new project on [Netlify](https://netlify.com) from your chosen Git provider. + +If you don't want to use the `netlify.toml`, when you go to [Netlify](https://netlify.com) and set up up a new project from Git, input the following settings: - **Build Command:** `astro build` or `npm run build` - **Publish directory:** `dist` -2. Hit the deploy button. +Then hit the deploy button. ## Google Firebase @@ -233,8 +249,8 @@ You can deploy your Astro project with Microsoft Azure [Static Web Apps](https:/ - Your app code pushed to [GitHub](https://github.com). - The [SWA Extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurestaticwebapps) in [Visual Studio Code](https://code.visualstudio.com). -Install the extension in VS Code and navigate to your app root. Open the Static Web Apps extension, sign in to Azure, and click the '+' sign to create a new Static Web App. You will be prompted to designate which subscription key to use. +Install the extension in VS Code and navigate to your app root. Open the Static Web Apps extension, sign in to Azure, and click the '+' sign to create a new Static Web App. You will be prompted to designate which subscription key to use. -Follow the wizard started by the extension to give your app a name, choose a framework preset, and designate the app root (usually `/`) and built file location `/dist`. The wizard will run and will create a GitHub action in your repo in a `.github` folder. +Follow the wizard started by the extension to give your app a name, choose a framework preset, and designate the app root (usually `/`) and built file location `/dist`. The wizard will run and will create a GitHub action in your repo in a `.github` folder. -The action will work to deploy your app (watch its progress in your repo's Actions tab) and, when successfully completed, you can view your app in the address provided in the extension's progress window by clicking the 'Browse Website' button that appears when the GitHub action has run. +The action will work to deploy your app (watch its progress in your repo's Actions tab) and, when successfully completed, you can view your app in the address provided in the extension's progress window by clicking the 'Browse Website' button that appears when the GitHub action has run. diff --git a/docs/guides/imports.md b/docs/guides/imports.md index 1085e216b..595f13e62 100644 --- a/docs/guides/imports.md +++ b/docs/guides/imports.md @@ -29,7 +29,7 @@ export function getUser() { } // src/index.js -import { getUser } from './user.js'; +import {getUser} from './user.js'; ``` All browsers now support ESM, so Astro is able to ship this code directly to the browser during development. @@ -38,7 +38,7 @@ All browsers now support ESM, so Astro is able to ship this code directly to the Astro includes built-in support to build TypeScript files (`*.ts`) to JavaScript. Astro components also support TypeScript in the frontmatter script section. -Note that this built-in support is build only. By default, Astro does not type-check your TypeScript code. +Note that this built-in support is build only. By default, Astro does not type-check your TypeScript code. <!-- To integrate type checking into your development/build workflow, add the [@snowpack/plugin-typescript](https://www.npmjs.com/package/@snowpack/plugin-typescript) plugin. --> @@ -46,7 +46,7 @@ Note that this built-in support is build only. By default, Astro does not type-c Astro includes built-in support to build JSX files (`*.jsx` & `*.tsx`) to JavaScript. -If you are using Preact, Astro will detect your Preact import and switch to use the Preact-style JSX `h()` function. This is all done automatically for you. +If you are using Preact, Astro will detect your Preact import and switch to use the Preact-style JSX `h()` function. This is all done automatically for you. **Note: Astro does not support JSX in `.js`/`.ts` files.** @@ -105,7 +105,7 @@ All other assets not explicitly mentioned above can be imported via ESM `import` const wasm = await WebAssembly.instantiateStreaming(fetch('/example.wasm')); ``` -Astro supports loading WASM files directly into your application using the browser's [`WebAssembly`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly) API. Read our [WASM guide](/docs/guides/wasm.md) to learn more. +Astro supports loading WASM files directly into your application using the browser's [`WebAssembly`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly) API. Read our [WASM guide](/guides/wasm) to learn more. ## NPM Packages @@ -121,7 +121,7 @@ When you start up your dev server or run a new build, you may see a message that ## Node Builtins -We encourage Astro users to avoid Node.js builtins (`fs`, `path`, etc) whenever possible. Astro aims to be compatible with multiple JavaScript runtimes in the future. This includes [Deno](https://deno.land/) and [Cloudflare Workers](https://workers.cloudflare.com/) which do not support Node builtin modules such as `fs`. +We encourage Astro users to avoid Node.js builtins (`fs`, `path`, etc) whenever possible. Astro aims to be compatible with multiple JavaScript runtimes in the future. This includes [Deno](https://deno.land/) and [Cloudflare Workers](https://workers.cloudflare.com/) which do not support Node builtin modules such as `fs`. Our aim is to provide Astro alternatives to common Node.js builtins. However, no such alternatives exist today. So, if you _really_ need to use these builtin modules we don't want to stop you. Astro supports Node.js builtins using Node's newer `node:` prefix. If you want to read a file, for example, you can do so like this: diff --git a/docs/guides/markdown-content.md b/docs/guides/markdown-content.md index 71d18fe7e..d1fe069ad 100644 --- a/docs/guides/markdown-content.md +++ b/docs/guides/markdown-content.md @@ -1,6 +1,6 @@ --- layout: ~/layouts/Main.astro -title: Markdown Content +title: Markdown --- Astro comes with out-of-the-box Markdown support powered by the expansive [remark](https://remark.js.org/) ecosystem. diff --git a/docs/guides/publish-to-npm.md b/docs/guides/publish-to-npm.md index 7c52fec02..aebf0311a 100644 --- a/docs/guides/publish-to-npm.md +++ b/docs/guides/publish-to-npm.md @@ -1,11 +1,11 @@ --- layout: ~/layouts/Main.astro -title: Publish Components to NPM +title: Publish a Component to NPM --- -Built a great Astro component? **Publish it to [npm!](https://npmjs.com/)** +Built a great Astro component? **Publish it to [npm!](https://npmjs.com/)** -Once published to npm, Astro components can be installed and used in your project like any other npm package. npm is a great way to share Astro components across projects within your team, your company, or the entire world. +Once published to npm, Astro components can be installed and used in your project like any other npm package. npm is a great way to share Astro components across projects within your team, your company, or the entire world. ## Basic NPM Package Setup @@ -66,7 +66,7 @@ import Capitalize from '@example/my-components/Capitalize.astro'; <Capitalize phrase={`Hello world`} /> ``` -This is a less common scenario, and we only recommend it if you have good reason. Because Astro is completely rendered at build-time, there are no client-side performance concerns to our default recommendation to export your components from a single `index.js` file. +This is a less common scenario, and we only recommend it if you have good reason. Because Astro is completely rendered at build-time, there are no client-side performance concerns to our default recommendation to export your components from a single `index.js` file. To support importing by file within your package, add each file to your **package.json** `exports` map: @@ -80,4 +80,4 @@ To support importing by file within your package, add each file to your **packag + "./Capitalize.astro": "./Capitalize.astro" } } -``` +```
\ No newline at end of file diff --git a/docs/guides/styling.md b/docs/guides/styling.md index 202c48640..725a83e46 100644 --- a/docs/guides/styling.md +++ b/docs/guides/styling.md @@ -1,26 +1,25 @@ --- layout: ~/layouts/Main.astro -title: Styling +title: Styling & CSS --- -## đ Quick Start +Astro includes special handling to make writing CSS as easy as possible. Styling inside of Astro components is done by adding a `<style>` tag anywhere. -Styling in an Astro component is done by adding a `<style>` tag anywhere. By default, all styles are **scoped**, meaning they only apply to the current component. To create global styles, add a `:global()` wrapper around a selector (the same as if you were using [CSS Modules][css-modules]). +By default, all Astro component styles are **scoped**, meaning they only apply to the current component. These styles are automatically extracted and optimized for you in the final build, so that you don't need to worry about style loading. + +To create global styles, add a `:global()` wrapper around a selector (the same as if you were using [CSS Modules][css-modules]). ```html <!-- src/components/MyComponent.astro --> - <style> /* Scoped class selector within the component */ .scoped { font-weight: bold; } - /* Scoped element selector within the component */ h1 { color: red; } - /* Global style */ :global(h1) { font-size: 32px; @@ -31,11 +30,8 @@ Styling in an Astro component is done by adding a `<style>` tag anywhere. By def <h1>I have both scoped and global styles</h1> ``` -**Tips** +đ Read our full guide on [Astro component syntax](/core-concepts/astro-components#css-styles) to learn more about using the `<style>` tag. -- `<style>` tags within `.astro` files will be extracted and optimized for you on build. So you can write CSS without worrying too much about delivery. -- For best result, only have one `<style>` tag per-Astro component. This isnât necessarily a limitation, but it may result in better optimization at buildtime. -- If you want to import third-party libraries into an Astro component, you can use [Sass][sass]! In particular, [@use][sass-use] may come in handy (e.g. `@use "bootstrap/scss/bootstrap"`); ## Cross-Browser Compatibility @@ -60,8 +56,7 @@ All styles in Astro are automatically [**autoprefixed**](#cross-browser-compatib --- -## Using Frameworks and Libraries - +## Frameworks and Libraries ### đ React / Preact `.jsx` files support both global CSS and CSS Modules. To enable the latter, use the `.module.css` extension (or `.module.scss`/`.module.sass` if using Sass). @@ -132,11 +127,20 @@ Now youâre ready to write Tailwind! Our recommended approach is to create a `p @tailwind utilities; ``` -đ As an alternative to `public/global.css`, You may also add Tailwind utilities to individual `pages/*.astro` components in `<style>` tags, but be mindful of duplication! If you end up creating multiple Tailwind-managed stylesheets for your site, make sure youâre not sending the same CSS to users over and over again in separate CSS files. +As an alternative to `public/global.css`, You may also add Tailwind utilities to individual `pages/*.astro` components in `<style>` tags, but be mindful of duplication! If you end up creating multiple Tailwind-managed stylesheets for your site, make sure youâre not sending the same CSS to users over and over again in separate CSS files. ---- +### Importing from npm + +If you want to import third-party libraries into an Astro component, you can use a `<style lang="scss">` tag to enable [Sass][sass] and use the [@use][sass-use] rule. -## đŚ Bundling +```html +<!-- Loads Boostrap --> +<style lang="scss"> + @use "bootstrap/scss/bootstrap"; +</style> +``` + +## Bundling All CSS is minified and bundled automatically for you in running `astro build`. Without getting too in the weeds, the general rules are: @@ -148,13 +152,11 @@ Weâll be expanding our styling optimization story over time, and would love yo _Note: be mindful when some page styles get extracted to the âcommonâ bundle, and some page styles stay on-page. For most people this may not pose an issue, but when part of your styles are bundled they technically may load in a different order and your cascade may be different. While problem isnât unique to Astro and is present in almost any CSS bundling process, it can be unexpected if youâre not anticipating it. Be sure to inspect your final production build, and please [report any issues][issues] you may come across._ ---- - -## đ Advanced Styling Architecture in Astro +## Advanced Styling Architecture Too many development setups take a hands-off approach to CSS, or at most leave you with only contrived examples that donât get you very far. Telling developers âUse whatever styling solution you want!â is a nice thought that rarely works out in practice. Few styling approaches lend themselves to every setup. Astro is no differentâcertain styling approaches _will_ work better than others. -An example to illustrate this: Astro removes runtime JS (even the core framework if possible). Thus, depending on Styled Components for all your styles would be bad, as that would require React to load on pages where itâs not needed. Or at best, youâd get a â[FOUC][fouc]â as your static HTML is served but the user waits for JavaScript to download and execute. Or consider a second example at the opposite end of the spectrum: _BEM_. You _can_ use a completely-decoupled [BEM][bem] or [SMACSS][smacss] approach in Astro. But thatâs a lot of manual maintenance you can avoid, and it leaves out a lof of convenience of [Astro components][astro-syntax]. +An example to illustrate this: Astro removes runtime JS (even the core framework if possible). Thus, depending on Styled Components for all your styles would be bad, as that would require React to load on pages where itâs not needed. Or at best, youâd get a â[FOUC][fouc]â as your static HTML is served but the user waits for JavaScript to download and execute. Or consider a second example at the opposite end of the spectrum: _BEM_. You _can_ use a completely-decoupled [BEM][bem] or [SMACSS][smacss] approach in Astro. But thatâs a lot of manual maintenance you can avoid, and it leaves out a lof of convenience of [Astro components](/core-concepts/astro-components). We think thereâs a great middle ground between intuitive-but-slow CSS-in-JS and fast-but-cumbersome global CSS: **Hybrid Scoped + Utility CSS**. This approach works well in Astro, is performant for users, and will be the best styling solution in Astro _for most people_ (provided youâre willing to learn a little). So as a quick recap: @@ -480,7 +482,6 @@ This guide wouldnât be possible without the following blog posts, which expand Also please check out the [Stylelint][stylelint] project to whip your styles into shape. You lint your JS, why not your CSS? -[astro-syntax]: ./syntax.md [autoprefixer]: https://github.com/postcss/autoprefixer [bem]: http://getbem.com/introduction/ [box-model]: https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/The_box_model |