diff options
Diffstat (limited to 'docs/src')
| -rw-r--r-- | docs/src/config.ts | 1 | ||||
| -rw-r--r-- | docs/src/pages/guides/data-fetching.md | 11 | ||||
| -rw-r--r-- | docs/src/pages/guides/environment-variables.md | 29 | ||||
| -rw-r--r-- | docs/src/pages/guides/styling.md | 206 | ||||
| -rw-r--r-- | docs/src/pages/reference/configuration-reference.md | 4 | ||||
| -rw-r--r-- | docs/src/pages/reference/renderer-reference.md | 48 |
6 files changed, 187 insertions, 112 deletions
diff --git a/docs/src/config.ts b/docs/src/config.ts index bad7219e5..c3d78dc8d 100644 --- a/docs/src/config.ts +++ b/docs/src/config.ts @@ -24,6 +24,7 @@ export const SIDEBAR = { { text: 'RSS', link: 'guides/rss' }, { text: 'Supported Imports', link: 'guides/imports' }, { text: 'Aliases', link: 'guides/aliases' }, + { text: 'Environment Variables', link: 'guides/environment-variables' }, { text: 'Deploy to the web', link: 'guides/deploy' }, { text: 'Publish to npm', link: 'guides/publish-to-npm' }, diff --git a/docs/src/pages/guides/data-fetching.md b/docs/src/pages/guides/data-fetching.md index 5f306a2dd..a0481f059 100644 --- a/docs/src/pages/guides/data-fetching.md +++ b/docs/src/pages/guides/data-fetching.md @@ -32,11 +32,10 @@ console.log(data); ## Using `fetch()` outside of Astro Components -If you want to use `fetch()` in a non-astro component, use the [`node-fetch`](https://github.com/node-fetch/node-fetch) library: +If you want to use `fetch()` in a non-astro component, it is also globally available: ```tsx // Movies.tsx -import fetch from 'node-fetch'; import type { FunctionalComponent } from 'preact'; import { h } from 'preact'; @@ -55,11 +54,3 @@ const Movies: FunctionalComponent = () => { export default Movies; ``` - -If you load a component using `node-fetch` [interactively](/core-concepts/component-hydration), with `client:load`, `client:visible`, etc., you'll need to either not use `node-fetch` or switch to an [isomorphic](https://en.wikipedia.org/wiki/Isomorphic_JavaScript) library that will run both at build time and on the client, as the [`node-fetch` README.md](https://github.com/node-fetch/node-fetch#motivation) recommends: - -> Instead of implementing XMLHttpRequest in Node.js to run browser-specific [Fetch polyfill](https://github.com/github/fetch), why not go from native http to fetch API directly? Hence, node-fetch, minimal code for a window.fetch compatible API on Node.js runtime. -> -> See Jason Miller's [isomorphic-unfetch](https://www.npmjs.com/package/isomorphic-unfetch) or Leonardo Quixada's [cross-fetch](https://github.com/lquixada/cross-fetch) for isomorphic usage (exports node-fetch for server-side, whatwg-fetch for client-side). - -> Quoted from https://github.com/node-fetch/node-fetch#motivation diff --git a/docs/src/pages/guides/environment-variables.md b/docs/src/pages/guides/environment-variables.md new file mode 100644 index 000000000..1f7f396ad --- /dev/null +++ b/docs/src/pages/guides/environment-variables.md @@ -0,0 +1,29 @@ +--- +layout: ~/layouts/MainLayout.astro +title: Using environment variables +description: Learn how to use environment variables in an Astro project. +--- + +Astro uses Vite for environment variables, and allows you to use any of its methods to get and set environment variables. Note that all environment variables must be prefixed with `VITE_` to be accessible by client side code. + +## Setting environment variables + +Vite includes `dotenv` by default, allowing you to easily set environment variables with no configuration in Astro projects. You can also attach a mode (either `production` or `development`) to the filename, like `.env.production` or `.env.development`, which makes the environment variables only take effect in that mode. + +Just create a `.env` file in the project directory and add some variables to it. + +```bash +# .env +VITE_POKEAPI="https://pokeapi.co/api/v2" +``` + +## Getting environment variables + +Instead of using `process.env`, with Vite you use `import.meta.env`, which uses the `import.meta` feature added in ES2020 (don't worry about browser support though, Vite replaces all `import.meta.env` mentions with static values). For example, to get the `VITE_POKEAPI` environment variable, you could use `import.meta.env.VITE_POKEAPI`. + +```js +fetch(`${import.meta.env.VITE_POKEAPI}/pokemon/squirtle` +``` + +> ⚠️WARNING⚠️: +> Because Vite statically replaces `import.meta.env`, you cannot access it with dynamic keys like `import.meta.env[key]`. diff --git a/docs/src/pages/guides/styling.md b/docs/src/pages/guides/styling.md index d0b5300dd..98df62b8a 100644 --- a/docs/src/pages/guides/styling.md +++ b/docs/src/pages/guides/styling.md @@ -6,62 +6,140 @@ description: Learn how to style components with Astro. 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. -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. +## Astro component styles -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. This can be very easy to work with, as you only have to worry about what’s in your current document at any given time. ```html <!-- src/components/MyComponent.astro --> <style> /* Scoped class selector within the component */ - .scoped { - font-weight: bold; + .text { + font-family: cursive; } /* Scoped element selector within the component */ h1 { color: red; } - /* Global style */ - :global(h1) { - font-size: 32px; - } </style> -<div class="scoped">I'm a scoped style and only apply to this component</div> -<h1>I have both scoped and global styles</h1> +<h1>I’m a scoped style and I’m red!</h1> +<p class="text">I'm a scoped style and I’m cursive!</p> ``` -To include every selector in a `<style>` as global styles, use `<style global>`. It's best to avoid using this escape hatch if possible, but it can be useful if you find yourself repeating `:global()` multiple times in the same `<style>`. +Note that the `h1` selector won’t bleed out of the current component! These styles won’t apply any other `h1` tags outside this document. Not even child components. + +_Tip: even though you can use element selectors, using classnames is preferred. This is not only slightly more performant, but is also easier to read, especially in a large document._ + +### Global styles + +Of course, the real power of CSS is being able to reuse as much as possible! The preferred method of loading global styles is by using a standard `<link>` tag like you’re used to. It can even be used in conjunction with Astro’s scoped `<style>` tag: ```html +<!-- src/pages/index.astro --> +<head> + <!-- load styles from src/styles/utils.css using Astro.resolve() --> + <link rel="stylesheet" type="text/css" + href={Astro.resolve('../styles/utils.css')} /> +</head> +<body> + <!-- scoped Astro styles that apply only to the current page (not to children or other components) --> + <style> + .title { + font-size: 32px; + font-weight: bold; + } + </style> + + <!-- the ".title" class is scoped, but we can also use our global "align-center" and "margin top: 4" utility classes from utils.css --> + <h1 class="title align-center mt4">Scoped Page Title</h1> +</body> +``` + +_Note: `Astro.resolve()` is a handy utility that helps resolve files from anywhere ([docs][astro-resolve])_ + +#### Styling children + +If you’d like scoped styles to apply to children, you can use the special `:global()` function borrowed from [CSS Modules][css-modules]: + +```astro <!-- src/components/MyComponent.astro --> +--- +import PostContent from './Post.astro'; +--- <style> - /* Scoped class selector within the component */ - .scoped { - font-weight: bold; - } - /* Scoped element selector within the component */ + /* Scoped to current component only */ h1 { color: red; } + + /* Scoped to all descendents of the scoped .blog-post class */ + .blog-post :global(h1) { + color: blue; + } </style> +<h1>Title</h1> +<article class="blog-post"> + <PostContent /> +</article> +``` + +This is a great way to style things like blog posts, or documents with CMS-powered content where the contents live outside of Astro. But be careful when styling children unconditionally, as it breaks component encapsulation. Components that appear different based on whether or not they have a certain parent component can become unwieldy quickly. + +#### Global styles within style tag + +If you’d like to use global styles but you don’t want to use a normal `<link>` tag (recommended), there is a `<style global>` escape hatch: + +```html <style global> - /* Global style */ + /* Applies to all h1 tags in your entire site */ h1 { font-size: 32px; } </style> -<div class="scoped">I'm a scoped style and only apply to this component</div> -<h1>I have both scoped and global styles</h1> +<h1>Globally-styled</h1> +``` + +You can achieve the same by using the `:global()` function at the root of a selector: + +```html +<style> + /* Applies to all h1 tags in your entire site */ + :global(h1) { + font-size: 32px; + } + + /* normal scoped h1 that applies to this file only */ + h1 { + color: blue; + } +</style> +``` + +It’s recommended to only use this in scenarios where a `<link>` tag won’t work. It’s harder to track down errant global styles when they’re scattered around and not in a central CSS file. + +📚 Read our full guide on [Astro component syntax][astro-component] to learn more about using the `<style>` tag. + +## Autoprefixer + +[Autoprefixer][autoprefixer] takes care of cross-browser CSS compatibility for you. Use it in astro by installing it (`npm install --save-dev autoprefixer`) and adding a `postcss.config.cjs` file to the root of your project: + +```js +// postcss.config.cjs +module.exports = { + autoprefixer: { + /* (optional) autoprefixer settings */ + }, +}; ``` -📚 Read our full guide on [Astro component syntax](/core-concepts/astro-components#css-styles) to learn more about using the `<style>` tag. +_Note: Astro v0.21 and later requires this manual setup for autoprefixer. Previous versions ran this automatically._ -## Cross-Browser Compatibility +## PostCSS -We also automatically add browser prefixes using [Autoprefixer][autoprefixer]. By default, Astro loads the [Browserslist defaults][browserslist-defaults], but you may also specify your own by placing a [Browserslist][browserslist] file in your project root. +You can use any PostCSS plugin by adding a `postcss.config.cjs` file to the root of your project. Follow the documentation for the plugin you’re trying to install for configuration and setup. --- @@ -78,7 +156,7 @@ Styling in Astro is meant to be as flexible as you'd like it to be! The followin ¹ _`.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)_ -All styles in Astro are automatically [**autoprefixed**](#cross-browser-compatibility), minified and bundled, so you can just write CSS and we'll handle the rest ✨. +All styles in Astro are automatically minified and bundled, so you can just write CSS and we'll handle the rest ✨. --- @@ -104,33 +182,36 @@ Vue in Astro supports the same methods as `vue-loader` does: Svelte in Astro also works exactly as expected: [Svelte Styling Docs][svelte-style]. -### 👓 Sass +### 🎨 CSS Preprocessors (Sass, Stylus, etc.) + +Astro supports CSS preprocessors such as [Sass][sass], [Stylus][stylus], and [Less][less] through [Vite][vite-preprocessors]. It can be enabled via the following: + +- **Sass**: Run `npm install -D sass` and use `<style lang="scss">` or `<style lang="sass">` (indented) in `.astro` files +- **Stylus**: Run `npm install -D stylus` and use `<style lang="styl">` or `<style lang="stylus">` in `.astro` files +- **Less**: Run `npm install -D less` and use `<style lang="less">` in `.astro` files. -Astro also supports [Sass][sass] out-of-the-box. To enable for each framework: +You can also use all of the above within JS frameworks as well! Simply follow the patterns each framework recommends: -- **Astro**: `<style lang="scss">` or `<style lang="sass">` - **React** / **Preact**: `import Styles from './styles.module.scss'`; -- **Vue**: `<style lang="scss">` or `<style lang="sass">` -- **Svelte**: `<style lang="scss">` or `<style lang="sass">` +- **Vue**: `<style lang="scss">` +- **Svelte**: `<style lang="scss">` -💁 Sass is great! If you haven't used Sass in a while, please give it another try. The new and improved [Sass Modules][sass-use] are a great fit with modern web development, and it's blazing-fast since being rewritten in Dart. And the best part? **You know it already!** Use `.scss` to write familiar CSS syntax you're used to, and only sprinkle in Sass features if/when you need them.' +Additionally, [PostCSS](#-postcss) is supported, but the setup is [slightly different](#-postcss). -**Note**: If you use .scss files rather than .css files, your stylesheet links should still point to .css files because of Astro’s auto-compilation process. When Astro “needs” the styling files, it’ll be “looking for” the final .css file(s) that it compiles from the .scss file(s). For example, if you have a .scss file at `./src/styles/global.scss`, use this link: `<link rel="stylesheet" href="{Astro.resolve('../styles/global.css')}">` — **not** `<link rel="stylesheet" href="{Astro.resolve('../styles/global.scss')}">`. +_Note: CSS inside `public/` will **not** be transformed! Place it within `src/` instead._ ### 🍃 Tailwind -> Note that Astro's Tailwind support _only_ works with Tailwind JIT mode. - Astro can be configured to use [Tailwind][tailwind] easily! Install the dependencies: ``` npm install --save-dev tailwindcss ``` -And also create a `tailwind.config.js` in your project root: +And create 2 files in your project root: `tailwind.config.cjs` and `postcss.config.cjs`: ```js -// tailwind.config.js +// tailwind.config.cjs module.exports = { mode: 'jit', purge: ['./public/**/*.html', './src/**/*.{astro,js,jsx,svelte,ts,tsx,vue}'], @@ -138,15 +219,11 @@ module.exports = { }; ``` -Be sure to add the config path to `astro.config.mjs`, so that Astro enables JIT support in the dev server. - -```diff - // astro.config.mjs - export default { -+ devOptions: { -+ tailwindConfig: './tailwind.config.js', -+ }, - }; +```js +// postcss.config.cjs +module.exports = { + tailwind: {}, +}; ``` Now you're ready to write Tailwind! Our recommended approach is to create a `src/styles/global.css` file (or whatever you‘d like to name your global stylesheet) with [Tailwind utilities][tailwind-utilities] like so: @@ -162,7 +239,7 @@ As an alternative to `src/styles/global.css`, You may also add Tailwind utilitie #### Migrating from v0.19 -As of [version 0.20.0](https://github.com/snowpackjs/astro/releases/tag/astro%400.20.0), Astro will no longer bundle, build and process `public/` files. Previously, we'd recommended putting your tailwind files in the `public/` directory. If you started a project with this pattern, you should move any Tailwind styles into the `src` directory and import them in your template using [Astro.resolve()](/reference/api-reference#astroresolve): +As of [version 0.20.0](https://github.com/snowpackjs/astro/releases/tag/astro%400.20.0), Astro will no longer bundle, build and process `public/` files. Previously, we'd recommended putting your tailwind files in the `public/` directory. If you started a project with this pattern, you should move any Tailwind styles into the `src` directory and import them in your template using [Astro.resolve()][astro-resolve]: ```astro <link @@ -171,44 +248,14 @@ As of [version 0.20.0](https://github.com/snowpackjs/astro/releases/tag/astro%40 > ``` -### 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. - -```html -<!-- Loads Boostrap --> -<style lang="scss"> - @use "bootstrap/scss/bootstrap"; -</style> -``` - ### 🎭 PostCSS -[PostCSS](https://postcss.org/) is a popular CSS transpiler with support for [a huge ecosystem of plugins.](https://github.com/postcss/postcss#plugins) - -**To use PostCSS with Snowpack:** add the [@snowpack/plugin-postcss](https://www.npmjs.com/package/@snowpack/plugin-postcss) plugin to your project. - -```diff -// snowpack.config.js -"plugins": [ -+ "@snowpack/plugin-postcss" -] -``` - -PostCSS requires a [`postcss.config.js`](https://github.com/postcss/postcss#usage) file in your project. By default, the plugin looks in the root directory of your project, but you can customize this yourself with the `config` option. See [the plugin README](https://www.npmjs.com/package/@snowpack/plugin-postcss) for all available options. - -```js -// postcss.config.js -// Example (empty) postcss config file -module.exports = { - plugins: [ - // ... - ], -}; -``` +Using PostCSS is as simple as placing a [`postcss.config.cjs`](https://github.com/postcss/postcss#usage) file in the root of your project. Be aware that this plugin will run on all CSS in your project, including any files that compiled to CSS (like `.scss` Sass files, for example). +_Note: CSS in `public/` **will not be transformed!** Instead, place it within `src/` if you’d like PostCSS to run over your styles._ + ## Bundling All CSS is minified and bundled automatically for you in running `astro build`. Without getting too in the weeds, the general rules are: @@ -550,6 +597,8 @@ This guide wouldn't be possible without the following blog posts, which expand o Also please check out the [Stylelint][stylelint] project to whip your styles into shape. You lint your JS, why not your CSS? [autoprefixer]: https://github.com/postcss/autoprefixer +[astro-component]: /core-concepts/astro-components#css-styles +[astro-resolve]: /reference/api-reference#astroresolve [bem]: http://getbem.com/introduction/ [box-model]: https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/The_box_model [browserslist]: https://github.com/browserslist/browserslist @@ -560,6 +609,7 @@ Also please check out the [Stylelint][stylelint] project to whip your styles int [css-treeshaking]: https://css-tricks.com/how-do-you-remove-unused-css-from-a-site/ [fouc]: https://en.wikipedia.org/wiki/Flash_of_unstyled_content [layout-isolated]: https://web.archive.org/web/20210227162315/https://visly.app/blogposts/layout-isolated-components +[less]: https://lesscss.org/ [issues]: https://github.com/snowpackjs/astro/issues [magic-number]: https://css-tricks.com/magic-numbers-in-css/ [material-ui]: https://material.io/components @@ -568,11 +618,13 @@ Also please check out the [Stylelint][stylelint] project to whip your styles int [sass-use]: https://sass-lang.com/documentation/at-rules/use [smacss]: http://smacss.com/ [styled-components]: https://styled-components.com/ +[stylus]: https://stylus-lang.com/ [styled-jsx]: https://github.com/vercel/styled-jsx [stylelint]: https://stylelint.io/ [svelte-style]: https://svelte.dev/docs#style [tailwind]: https://tailwindcss.com [tailwind-utilities]: https://tailwindcss.com/docs/adding-new-utilities#using-css [utility-css]: https://frontstuff.io/in-defense-of-utility-first-css +[vite-preprocessors]: https://vitejs.dev/guide/features.html#css-pre-processors [vue-css-modules]: https://vue-loader.vuejs.org/guide/css-modules.html [vue-scoped]: https://vue-loader.vuejs.org/guide/scoped-css.html diff --git a/docs/src/pages/reference/configuration-reference.md b/docs/src/pages/reference/configuration-reference.md index c181c0ea2..071179b59 100644 --- a/docs/src/pages/reference/configuration-reference.md +++ b/docs/src/pages/reference/configuration-reference.md @@ -22,7 +22,3 @@ export default /** @type {import('astro').AstroUserConfig} */ ( } ); ``` - -## Snowpack Config - -Astro is powered internally by Snowpack. You can configure Snowpack directly by creating a `snowpack.config.mjs` file. See [snowpack.dev](https://www.snowpack.dev/reference/configuration) for full documentation on this file. diff --git a/docs/src/pages/reference/renderer-reference.md b/docs/src/pages/reference/renderer-reference.md index a4bd63bf4..0e8dc1a79 100644 --- a/docs/src/pages/reference/renderer-reference.md +++ b/docs/src/pages/reference/renderer-reference.md @@ -38,8 +38,8 @@ A renderer should include any framework dependencies as package dependencies. Fo // package.json "name": "@astrojs/renderer-react", "dependencies": { - "react": "^17.0.0", - "react-dom": "^17.0.0" + "react": "^17.0.2", + "react-dom": "^17.0.2" } ``` @@ -49,22 +49,32 @@ This means that Astro users don't need to install the UI framework packages them The main entrypoint of a renderer is a simple JS file which exports a manifest for the renderer. The required values are `name`, `server`, and `client`. -Additionally, this entrypoint can define a [Snowpack plugin](https://www.snowpack.dev/guides/plugins) that should be used to load non-JavaScript files. +Additionally, this entrypoint can define a [Vite config object](https://vitejs.dev/config/) that should be used to load non-JavaScript files. ```js +import myVitePlugin from 'vite-plugin-myplugin'; + export default { name: '@astrojs/renderer-xxx', // the renderer name client: './client.js', // relative path to the client entrypoint - server: './server.js', // optional, relative path to the server entrypoint - snowpackPlugin: '@snowpack/plugin-xxx', // optional, the name of a snowpack plugin to inject - snowpackPluginOptions: { example: true }, // optional, any options to be forwarded to the snowpack plugin - knownEntrypoints: ['framework'], // optional, entrypoint modules that will be used by compiled source - external: ['dep'], // optional, dependencies that should not be built by snowpack - polyfills: ['./shadow-dom-polyfill.js'], // optional, module scripts that should be loaded before client hydration. - hydrationPolyfills: ['./hydrate-framework.js'], // optional, polyfills that need to run before hydration ever occurs. - jsxImportSource: 'preact', // optional, the name of the library from which JSX is imported - jsxTransformOptions: async () => { - // optional, a function to transform JSX files + server: './server.js', // (optional) relative path to the server entrypoint + viteConfig(options = { mode: 'development', command: 'serve' }) { + // (optional) return config object for Vite (https://vitejs.dev/config/) + return { + plugins: [myVitePlugin()], // tip: usually this will depend on a Vite plugin + optimizeDeps: { + include: ['my-client-dep'], // tip: it’s always a good idea to specify any client-side hydration deps here + }, + ssr: { + external: ['my-client-dep/node/server.js'], // tip: use ssr.external in case you encounter code meant only for Node + }, + }; + }, + polyfills: ['./shadow-dom-polyfill.js'], // (optional) scripts that should be injected on the page for the component + hydrationPolyfills: ['./hydrate-framework.js'], // (optional) polyfills that need to run before hydration ever occurs + jsxImportSource: 'preact', // (optional) the name of the library from which JSX is imported ("react", "preact", "solid-js", etc.) + jsxTransformOptions: async (options = { mode: 'development', ssr: true }) => { + // (optional) a function to transform JSX files const { default: { default: jsx }, } = await import('@babel/plugin-transform-react-jsx'); @@ -91,19 +101,15 @@ This is an `async` function that returns information about how to transform matc > Keep in mind that this transform doesn't need to handle TSX separately from JSX, Astro handles that for you! -The arguments passed to `jsxTransformOptions` follow Snowpack's `load()` plugin hook. These allow you to pass separate Babel configurations for various conditions, like if your files should be compiled differently in SSR mode. +`jsxTransformOptions` receives context about whether it’s running in `development` or `production` mode, as well as whether or not it’s running in SSR or client hydration. These allow you to pass separate Babel configurations for various conditions, like if your files should be compiled differently in SSR mode. ```ts export interface JSXTransformOptions { (context: { - /** True if builder is in dev mode (`astro dev`) */ - isDev: boolean; - /** True if HMR is enabled (add any HMR code to the output here). */ - isHmrEnabled: boolean; + /** "development" or "production" */ + mode: string; /** True if builder is in SSR mode */ - isSSR: boolean; - /** True if file being transformed is inside of a package. */ - isPackage: boolean; + ssr: boolean; }) => { plugins?: any[]; presets?: any[]; |