--- layout: ~/layouts/MainLayout.astro title: API Reference --- ## `Astro` global The `Astro` global is available in all contexts in `.astro` files. It has the following functions: ### `Astro.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](/core-concepts/collections). ```jsx // ./src/components/my-component.astro --- const data = Astro.fetchContent('../pages/post/*.md'); // returns an array of posts that live at ./src/pages/post/*.md ---
{data.slice(0, 3).map((post) => (

{post.title}

{post.description}

Read more
))}
``` `.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: ```js { /** frontmatter from the post.. example frontmatter: title: '', tag: '', date: '', image: '', author: '', description: '', **/ astro: { headers: [], // an array of h1...h6 elements in the markdown file source: '' // raw source of the markdown file html: '' // rendered HTML of the markdown file }, url: '' // the rendered path }[] ``` ### `Astro.request` `Astro.request` returns an object with the following properties: | Name | Type | Description | | :------------- | :---- | :---------------------------------------------- | | `url` | `URL` | The URL of the request being rendered. | | `canonicalURL` | `URL` | [Canonical URL][canonical] of the current page. | ⚠️ Temporary restriction: this is only accessible in top-level pages and not in sub-components. ### `Astro.site` `Astro.site` returns a `URL` made from `buildOptions.site` in your Astro config. If undefined, this will return a URL generated from `localhost`. ## Collections API A collection is any file in the `src/pages` directory that starts with a dollar sign (`$`) and includes an exported `createCollection` function in the component script. Check out our [Astro Collections](/core-concepts/collections) guide for more information and examples. ### `createCollection()` ```jsx --- export async function createCollection() { return { /* ... */ }; } --- ``` ⚠️ The `createCollection()` function executes in its own isolated scope before page loads. Therefore you can't reference anything from its parent scope, other than file imports. The compiler will warn if you break this requirement. The `createCollection()` function should returns an object of the following shape: | Name | Type | Description | | :--------- | :--------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `route` | `string` | **Required.** A route pattern for matching URL requests. This is used to generate the page URL in your final build. It must begin with the file name: for example, `pages/$tags.astro` must return a `route` that starts with `/tags/`. | | `paths` | `{params: Params}[]` | Return an array of all URL to be generated. | | `props` | `async ({ params, paginate }) => object` | **Required.** Load data for the page that will get passed to the page component as props. | | `paginate` | `boolean` | Optional: Enable automatic pagination. See next section. | | `rss` | [RSS](/reference/api-reference#rss-feed) | Optional: generate an RSS 2.0 feed from this collection ([docs](/reference/api-reference#rss-feed)) | ### Pagination Enable pagination for a collection by returning `paginate: true` from `createCollection()`. This passes a `paginate()` argument to `props()` that you can use to return paginated data in your HTML template via props. The `paginate()` function that you use inside of `props()` has the following interface: ```ts /* the "paginate()" passed to props({paginate}) */ type PaginateFunction = ( data: any[], args?: { /* pageSize: set the number of items to be shown on every page. Defaults to 10. */ pageSize?: number; } ) => PaginatedCollectionResult; /* the paginated return value, aka the prop passed to every page in the collection. */ interface PaginatedCollectionResult { /** result */ data: any[]; /** metadata */ /** the count of the first item on the page, starting from 0 */ start: number; /** the count of the last item on the page, starting from 0 */ end: number; /** total number of results */ total: number; page: { /** the current page number, starting from 1 */ current: number; /** number of items per page (default: 25) */ size: number; /** number of last page */ last: number; }; url: { /** url of the current page */ current: string; /** url of the previous page (if there is one) */ prev: string | undefined; /** url of the next page (if there is one) */ next: string | undefined; }; } ``` 📚 Learn more about pagination (and see an example) in our [Astro Collections guide.](/core-concepts/collections). ### RSS Create an RSS 2.0 feed for a collection by returning `paginate: true` & an `rss` object from `createCollection()`. The `rss` object will be used to generate the contents of the RSS XML file. The `rss` object follows the `CollectionRSS`data type: ```ts export interface CollectionRSS { /** (required) Title of the RSS Feed */ title: string; /** (required) Description of the RSS Feed */ description: string; /** Specify arbitrary metadata on opening tag */ xmlns?: Record; /** Specify custom data in opening of file */ customData?: string; /** Return data about each item */ item: (item: T) => { /** (required) Title of item */ title: string; /** (required) Link to item */ link: string; /** Publication date of item */ pubDate?: Date; /** Item description */ description?: string; /** Append some other XML-valid data to this item */ customData?: string; }; } ``` 📚 Learn more about RSS feed generation (and see an example) in our [Astro Collections guide.](/core-concepts/collections). ## `import.meta` > In this section we use `[dot]` to mean `.`. This is because of a bug in our build engine that is rewriting `import[dot]meta[dot]env` if we use `.` instead of `[dot]`. All ESM modules include a `import.meta` property. Astro adds `import[dot]meta[dot]env` through [Snowpack](https://www.snowpack.dev/). **`import[dot]meta[dot]env[dot]SSR`** can be used to know when rendering on the server. Sometimes you might want different logic, for example a component that should only be rendered in the client: ```jsx import { h } from 'preact'; export default function () { // Note: rewrite "[dot]" to "." for this to to work in your project. return import[dot]meta[dot]env[dot]SSR ? : ; } ``` [canonical]: https://en.wikipedia.org/wiki/Canonical_link_element ndexes Unnamed repository; edit this file 'description' to name the repository.
aboutsummaryrefslogtreecommitdiff
path: root/examples/env-vars/astro.config.mjs (unfollow)
AgeCommit message (Expand)AuthorFilesLines
2022-03-02[ci] collect statsGravatar FredKSchott 1-0/+1
2022-03-01fix failing format command in CI (#2696)Gravatar Fred K. Schott 7-128/+60
2022-03-01fix vite version (#2694)Gravatar Fred K. Schott 2-5/+5
2022-03-01fix: disable HMR during build (#2684)Gravatar Nate Moore 2-0/+6
2022-03-01[ci] update smoke tests (remote) (#2690)Gravatar github-actions[bot] 2-6/+4
2022-03-01[ci] collect statsGravatar FredKSchott 1-0/+1
2022-02-28[ci] update smoke tests (remote) (#2686)Gravatar github-actions[bot] 96-3363/+8217
2022-02-28[ci] update lockfile (#2687)Gravatar Fred K. Schott 1-101/+75
2022-03-01[ci] collect statsGravatar FredKSchott 1-0/+1
2022-02-28update ci branch nameGravatar Fred K. Schott 1-0/+2
2022-02-28Make smoke tests more deterministic (#2618)Gravatar Fred K. Schott 336-147/+34315
2022-02-28[ci] yarn formatGravatar natemoo-re 1-20/+20
2022-02-28[ci] release (#2683)astro@0.23.3Gravatar github-actions[bot] 31-54/+55
2022-02-28Fix typo (#2674)Gravatar Robin Millette 1-1/+1
2022-02-28[ci] update lockfile (#2676)Gravatar Fred K. Schott 1-6/+6
2022-02-28fix(runtime): do not render empty Fragment (#2667)Gravatar Mateus Esdras 1-0/+3
2022-02-28fix(hmr): HMR regression related to .astro updates (#2681)Gravatar Nate Moore 6-7/+24
2022-02-28Fix HTMLElement expression warning (#2675)Gravatar Jonathan Neal 1-1/+1
2022-02-28[ci] collect statsGravatar FredKSchott 1-0/+1
2022-02-27[ci] update lockfile (#2668)Gravatar Fred K. Schott 1-80/+80
2022-02-27[ci] collect statsGravatar FredKSchott 1-0/+1
2022-02-26[ci] collect statsGravatar FredKSchott 1-0/+1
2022-02-25[ci] yarn formatGravatar natemoo-re 1-20/+20
2022-02-25[ci] release (#2666)astro@0.23.2Gravatar github-actions[bot] 32-59/+57
2022-02-25[ci] yarn formatGravatar natemoo-re 2-12/+6
2022-02-25fix astro scoping of "@import" inside of style tags (#2656)Gravatar Fred K. Schott 3-6/+35
2022-02-25[ci] update lockfile (#2659)Gravatar Fred K. Schott 1-20/+20
2022-02-25feat: improve third-party Astro package compatability (#2665)Gravatar Nate Moore 3-6/+100
2022-02-25get new example working during buildGravatar Fred K. Schott 4-16/+21
2022-02-25[ci] yarn formatGravatar FredKSchott 1-7/+6
2022-02-25Add Non-HTML Pages example (#2637)Gravatar Joel Kuzmarski 11-0/+136
2022-02-25[ci] collect statsGravatar FredKSchott 1-0/+1
2022-02-24[ci] yarn formatGravatar natemoo-re 2-24/+24
2022-02-24[ci] release (#2641)astro@0.23.1@astrojs/markdown-remark@0.6.2Gravatar github-actions[bot] 38-90/+81
2022-02-24ensure utf8 encoding when serving html (#2654)Gravatar Fred K. Schott 3-4/+9
2022-02-24fix(core): Issue #2625. error with process.env.LANG larger than 5 (#2645)Gravatar Javier Cortés 2-1/+6
2022-02-24[ci] update lockfile (#2646)Gravatar Fred K. Schott 1-130/+124
2022-02-24chore: upgrade compiler (#2653)Gravatar Nate Moore 3-11/+11
2022-02-24[ci] yarn formatGravatar natemoo-re 2-5/+5
2022-02-24Add fine-grained HMR support (#2649)Gravatar Nate Moore 7-36/+37
2022-02-24[ci] collect statsGravatar FredKSchott 1-0/+1
2022-02-23Fixed incorrect types and imports (#2630)Gravatar Juan Martín Seery 27-35/+37
2022-02-23Add sass dev dep to blog-multiple-authors example (#2643)Gravatar Joel Kuzmarski 1-1/+2
2022-02-23Fix(component): align starting position in Markdown slot (#2631)Gravatar Shinobu Hayashi 4-6/+61
2022-02-23[ci] yarn formatGravatar matthewp 1-1/+1
2022-02-23Run all smoke tests with the static build (#2609)Gravatar Matthew Phillips 2-26/+32
2022-02-23[ci] collect statsGravatar FredKSchott 1-0/+1
2022-02-22[ci] update lockfile (#2624)Gravatar Fred K. Schott 1-171/+201
2022-02-22Fixed shiki import to work with "type": "module" (#2628)Gravatar Juan Martín Seery 3-5/+13