diff --git a/astro.sidebar.ts b/astro.sidebar.ts index 96d1a7863e908..23849daea8363 100644 --- a/astro.sidebar.ts +++ b/astro.sidebar.ts @@ -142,13 +142,14 @@ export const sidebar = [ group('reference.experimental', { items: [ 'reference/experimental-flags', + 'reference/experimental-flags/csp', 'reference/experimental-flags/fonts', + 'reference/experimental-flags/live-content-collections', 'reference/experimental-flags/client-prerender', 'reference/experimental-flags/content-intellisense', 'reference/experimental-flags/preserve-scripts-order', 'reference/experimental-flags/heading-id-compat', - 'reference/experimental-flags/csp', - 'reference/experimental-flags/live-content-collections', + 'reference/experimental-flags/raw-env-values', ], }), 'reference/legacy-flags', diff --git a/src/content/docs/en/guides/content-collections.mdx b/src/content/docs/en/guides/content-collections.mdx index 688204c8c0847..eb2b191cce321 100644 --- a/src/content/docs/en/guides/content-collections.mdx +++ b/src/content/docs/en/guides/content-collections.mdx @@ -23,7 +23,7 @@ Projects may continue using the legacy Content Collections API introduced in Ast You can define a **collection** from a set of data that is structurally similar. This can be a directory of blog posts, a JSON file of product items, or any data that represents multiple items of the same shape. -Collections stored locally in your project or on your filesystem can have entries of Markdown, MDX, Markdoc, YAML, or JSON files: +Collections stored locally in your project or on your filesystem can have entries of Markdown, MDX, Markdoc, YAML, TOML, or JSON files: - src/ @@ -85,7 +85,7 @@ The Content Layer API allows you to fetch your content (whether stored locally i Astro provides [two built-in loader functions](/en/reference/content-loader-reference/#built-in-loaders) (`glob()` and `file()`) for fetching your local content, as well as access to the API to construct your own loader and fetch remote data. -The [`glob()` loader](/en/reference/content-loader-reference/#glob-loader) creates entries from directories of Markdown, MDX, Markdoc, JSON, or YAML files from anywhere on the filesystem. It accepts a `pattern` of entry files to match using glob patterns supported by [micromatch](https://github.com/micromatch/micromatch#matching-features), and a base file path of where your files are located. Each entry's `id` will be automatically generated from its file name. Use this loader when you have one file per entry. +The [`glob()` loader](/en/reference/content-loader-reference/#glob-loader) creates entries from directories of Markdown, MDX, Markdoc, JSON, YAML, or TOML files from anywhere on the filesystem. It accepts a `pattern` of entry files to match using glob patterns supported by [micromatch](https://github.com/micromatch/micromatch#matching-features), and a base file path of where your files are located. Each entry's `id` will be automatically generated from its file name. Use this loader when you have one file per entry. The [`file()` loader](/en/reference/content-loader-reference/#file-loader) creates multiple entries from a single local file. Each entry in the file must have a unique `id` key property. It accepts a `base` file path to your file and optionally a [`parser` function](#parser-function) for data files it cannot parse automatically. Use this loader when your data file can be parsed as an array of objects. @@ -122,35 +122,17 @@ export const collections = { blog, dogs, probes }; ##### `parser` function -The `file()` loader accepts a second argument that defines a `parser` function. This allows you to specify a custom parser (e.g. `toml.parse` or `csv-parse`) to create a collection from a file's contents. +The `file()` loader accepts a second argument that defines a `parser` function. This allows you to specify a custom parser (e.g. `csv-parse`) to create a collection from a file's contents. -The `file()` loader will automatically detect and parse a single array of objects from JSON and YAML files (based on their file extension) with no need for a `parser` unless you have a [nested JSON document](#nested-json-documents). To use other files, such as `.toml` and `.csv`, you will need a to create a parser function. +The `file()` loader will automatically detect and parse (based on their file extension) a single array of objects from JSON and YAML files, and will treat each top-level table as an independent entry in TOML files. Support for these file types is built-in, and there is no need for a `parser` unless you have a [nested JSON document](#nested-json-documents). To use other files, such as `.csv`, you will need to create a parser function. -The following example defines a content collection `dogs` using a `.toml` file: - -```toml title="src/data/dogs.toml" -[[dogs]] -id = "..." -age = "..." - -[[dogs]] -id = "..." -age = "..." -``` - -After importing TOML's parser, you can load the `dogs` collection into your project by passing both a file path and `parser` function to the `file()` loader. A similar process can be used to define a `cats` collection from a `.csv` file: +The following example shows importing a CSV parser, then loading a `cats` collection into your project by passing both a file path and `parser` function to the `file()` loader: ```typescript title="src/content.config.ts" import { defineCollection } from "astro:content"; import { file } from "astro/loaders"; -import { parse as parseToml } from "toml"; import { parse as parseCsv } from "csv-parse/sync"; -const dogs = defineCollection({ - loader: file("src/data/dogs.toml", { parser: (text) => parseToml(text).dogs }), - schema: /* ... */ -}) - const cats = defineCollection({ loader: file("src/data/cats.csv", { parser: (text) => parseCsv(text, { columns: true, skipEmptyLines: true })}) }); diff --git a/src/content/docs/en/reference/errors/data-collection-entry-parse-error.mdx b/src/content/docs/en/reference/errors/data-collection-entry-parse-error.mdx index 787982e2ae2c5..cb5571c4b72f5 100644 --- a/src/content/docs/en/reference/errors/data-collection-entry-parse-error.mdx +++ b/src/content/docs/en/reference/errors/data-collection-entry-parse-error.mdx @@ -16,7 +16,7 @@ import DontEditWarning from '~/components/DontEditWarning.astro' > `COLLECTION_ENTRY_NAME` failed to parse. ## What went wrong? -Collection entries of `type: 'data'` must return an object with valid JSON (for `.json` entries) or YAML (for `.yaml` entries). +Collection entries of `type: 'data'` must return an object with valid JSON (for `.json` entries), YAML (for `.yaml` entries) or TOML (for `.toml` entries). diff --git a/src/content/docs/en/reference/errors/file-parser-not-found.mdx b/src/content/docs/en/reference/errors/file-parser-not-found.mdx index 5ec4611ab7310..fb1e433ea18fd 100644 --- a/src/content/docs/en/reference/errors/file-parser-not-found.mdx +++ b/src/content/docs/en/reference/errors/file-parser-not-found.mdx @@ -16,7 +16,7 @@ import DontEditWarning from '~/components/DontEditWarning.astro' > **FileParserNotFound**: No parser was found for 'FILE_NAME'. Pass a parser function (e.g. `parser: csv`) to the `file` loader. ## What went wrong? -The `file` loader can’t determine which parser to use. Please provide a custom parser (e.g. `toml.parse` or `csv-parse`) to create a collection from your file type. +The `file` loader can’t determine which parser to use. Please provide a custom parser (e.g. `csv-parse`) to create a collection from your file type. **See Also:** - [Passing a `parser` to the `file` loader](/en/guides/content-collections/#parser-function) diff --git a/src/content/docs/en/reference/experimental-flags/raw-env-values.mdx b/src/content/docs/en/reference/experimental-flags/raw-env-values.mdx new file mode 100644 index 0000000000000..fc3e89f61d750 --- /dev/null +++ b/src/content/docs/en/reference/experimental-flags/raw-env-values.mdx @@ -0,0 +1,50 @@ +--- +title: Experimental raw environment variables values +sidebar: + label: Raw environment variables +i18nReady: true +--- + +import Since from '~/components/Since.astro' + +

+ +**Type:** `boolean`
+**Default:** `false`
+ +

+ +Astro allows you to configure a [type-safe schema for your environment variables](/en/guides/environment-variables/#type-safe-environment-variables), and converts variables imported via `astro:env` into the expected type. + +However, Astro also converts your environment variables used through `import.meta.env` in some cases, and this can prevent access to some values such as the strings `"true"` (which is converted to a boolean value), and `"1"` (which is converted to a number). + +The `experimental.rawEnvValues` flag disables coercion of `import.meta.env` values that are populated from `process.env`, allowing you to use the raw value. + +To disable Astro's coercion on values used through `import.meta.env`, set the `experimental.rawEnvValues` flag to `true` in your Astro configuration: + +```js title="astro.config.mjs" ins={4-6} +import { defineConfig } from "astro/config" + +export default defineConfig({ + experimental: { + rawEnvValues: true, + } +}) +``` + +## Usage + +Enabling this experimental flag will no longer convert string values into booleans or numbers. This aligns `import.meta.env`'s behavior in Astro with [Vite](https://vite.dev/guide/env-and-mode.html#env-variables). + +In a future major version, Astro will switch to not coercing `import.meta.env` values by default, but you can opt in to the future behavior early using the `experimental.rawEnvValues` flag and if necessary, [updating your project](#updating-your-project) accordingly. + +### Updating your project + +If you were relying on this coercion, you may need to update your project code to apply it manually: + +```ts title="src/components/MyComponent.astro" del={1} ins={2} +const enabled: boolean = import.meta.env.ENABLED +const enabled: boolean = import.meta.env.ENABLED === "true" +``` + +If you need coercion in Astro, we recommend you use [`astro:env`](/en/guides/environment-variables/).