diff --git a/astro.sidebar.ts b/astro.sidebar.ts index 23849daea8363..d687faf69ba66 100644 --- a/astro.sidebar.ts +++ b/astro.sidebar.ts @@ -149,7 +149,8 @@ export const sidebar = [ 'reference/experimental-flags/content-intellisense', 'reference/experimental-flags/preserve-scripts-order', 'reference/experimental-flags/heading-id-compat', - 'reference/experimental-flags/raw-env-values', + 'reference/experimental-flags/static-import-meta-env', + 'reference/experimental-flags/chrome-devtools-workspace', ], }), 'reference/legacy-flags', diff --git a/src/content/docs/en/guides/integrations-guide/sitemap.mdx b/src/content/docs/en/guides/integrations-guide/sitemap.mdx index 77ffaf45e1ffa..930c1c8251933 100644 --- a/src/content/docs/en/guides/integrations-guide/sitemap.mdx +++ b/src/content/docs/en/guides/integrations-guide/sitemap.mdx @@ -9,6 +9,7 @@ category: other i18nReady: true --- import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; +import Since from '~/components/Since.astro'; This **[Astro integration][astro-integration]** generates a sitemap based on your pages when you build your Astro project. @@ -93,7 +94,7 @@ import { defineConfig } from 'astro/config'; import sitemap from '@astrojs/sitemap'; export default defineConfig({ - site: 'https://stargazers.club', + site: 'https://example.com', integrations: [sitemap()], // ... }); @@ -112,7 +113,7 @@ For extremely large sites, there may also be additional numbered files like `sit - https://stargazers.club/sitemap-0.xml + https://example.com/sitemap-0.xml ``` @@ -121,10 +122,10 @@ For extremely large sites, there may also be additional numbered files like `sit - https://stargazers.club/ + https://example.com/ - https://stargazers.club/second-page/ + https://example.com/second-page/ ``` @@ -201,10 +202,10 @@ import { defineConfig } from 'astro/config'; import sitemap from '@astrojs/sitemap'; export default defineConfig({ - site: 'https://stargazers.club', + site: 'https://example.com', integrations: [ sitemap({ - filter: (page) => page !== 'https://stargazers.club/secret-vip-lounge/', + filter: (page) => page !== 'https://example.com/secret-vip-lounge/', }), ], }); @@ -219,14 +220,14 @@ import { defineConfig } from 'astro/config'; import sitemap from '@astrojs/sitemap'; export default defineConfig({ - site: 'https://stargazers.club', + site: 'https://example.com', integrations: [ sitemap({ filter: (page) => - page !== 'https://stargazers.club/secret-vip-lounge-1/' && - page !== 'https://stargazers.club/secret-vip-lounge-2/' && - page !== 'https://stargazers.club/secret-vip-lounge-3/' && - page !== 'https://stargazers.club/secret-vip-lounge-4/', + page !== 'https://example.com/secret-vip-lounge-1/' && + page !== 'https://example.com/secret-vip-lounge-2/' && + page !== 'https://example.com/secret-vip-lounge-3/' && + page !== 'https://example.com/secret-vip-lounge-4/', }), ], }); @@ -234,17 +235,46 @@ export default defineConfig({ ### customPages -In some cases, a page might be part of your deployed site but not part of your Astro project. If you'd like to include a page in your sitemap that *isn't* created by Astro, you can use this option. +An array of externally-generated pages to be included in the generated sitemap file. + +Use this option to include pages in your sitemap that are a part of your deployed site but are not created by Astro. + +```js title="astro.config.mjs" ins={8} +import { defineConfig } from 'astro/config'; +import sitemap from '@astrojs/sitemap'; + +export default defineConfig({ + site: 'https://example.com', + integrations: [ + sitemap({ + customPages: ['https://example.com/external-page1', 'https://example.com/external-page2'], + }), + ], +}); +``` + +### customSitemaps + +

+ +**Type:** `string[]`
+**Default:** `[]`
+ +

+ +An array of externally-generated sitemaps to be included in the `sitemap-index.xml` file along with the generated sitemap entries. + +Use this option to include external sitemaps in the `sitemap-index.xml` file created by Astro for sections of your deployed site that have their own sitemaps not created by Astro. This is helpful when you host multiple services under the same domain. ```js title="astro.config.mjs" ins={8} import { defineConfig } from 'astro/config'; import sitemap from '@astrojs/sitemap'; export default defineConfig({ - site: 'https://stargazers.club', + site: 'https://example.com', integrations: [ sitemap({ - customPages: ['https://stargazers.club/external-page', 'https://stargazers.club/external-page2'], + customSitemaps: ['https://example.com/blog/sitemap.xml', 'https://example.com/shop/sitemap.xml'], }), ], }); @@ -259,7 +289,7 @@ import { defineConfig } from 'astro/config'; import sitemap from '@astrojs/sitemap'; export default defineConfig({ - site: 'https://stargazers.club', + site: 'https://example.com', integrations: [ sitemap({ entryLimit: 10000, @@ -283,7 +313,7 @@ import { defineConfig } from 'astro/config'; import sitemap from '@astrojs/sitemap'; export default defineConfig({ - site: 'https://stargazers.club', + site: 'https://example.com', integrations: [ sitemap({ changefreq: 'weekly', @@ -319,7 +349,7 @@ import { defineConfig } from 'astro/config'; import sitemap from '@astrojs/sitemap'; export default defineConfig({ - site: 'https://stargazers.club', + site: 'https://example.com', integrations: [ sitemap({ serialize(item) { @@ -356,11 +386,11 @@ import { defineConfig } from 'astro/config'; import sitemap from '@astrojs/sitemap'; export default defineConfig({ - site: 'https://stargazers.club', + site: 'https://example.com', integrations: [ sitemap({ i18n: { - defaultLocale: 'en', // All urls that don't contain `es` or `fr` after `https://stargazers.club/` will be treated as default locale, i.e. `en` + defaultLocale: 'en', // All urls that don't contain `es` or `fr` after `https://example.com/` will be treated as default locale, i.e. `en` locales: { en: 'en-US', // The `defaultLocale` value must present in `locales` keys es: 'es-ES', @@ -377,28 +407,28 @@ The resulting sitemap looks like this: ```xml title="sitemap-0.xml" ... - https://stargazers.club/ - - - + https://example.com/ + + + - https://stargazers.club/es/ - - - + https://example.com/es/ + + + - https://stargazers.club/fr/ - - - + https://example.com/fr/ + + + - https://stargazers.club/es/second-page/ - - - + https://example.com/es/second-page/ + + + ... ``` @@ -434,7 +464,7 @@ import { defineConfig } from 'astro/config'; import sitemap from '@astrojs/sitemap'; export default defineConfig({ - site: 'https://stargazers.club', + site: 'https://example.com', integrations: [ sitemap({ filenameBase: 'astronomy-sitemap' @@ -443,7 +473,7 @@ export default defineConfig({ }); ``` -The given configuration will generate sitemap files at `https://stargazers.club/astronomy-sitemap-0.xml` and `https://stargazers.club/astronomy-sitemap-index.xml`. +The given configuration will generate sitemap files at `https://example.com/astronomy-sitemap-0.xml` and `https://example.com/astronomy-sitemap-index.xml`. ## Examples diff --git a/src/content/docs/en/reference/experimental-flags/chrome-devtools-workspace.mdx b/src/content/docs/en/reference/experimental-flags/chrome-devtools-workspace.mdx new file mode 100644 index 0000000000000..f7f5f5d8b21ae --- /dev/null +++ b/src/content/docs/en/reference/experimental-flags/chrome-devtools-workspace.mdx @@ -0,0 +1,51 @@ +--- +title: Experimental Chrome DevTools workspace +sidebar: + label: Chrome DevTools workspace +i18nReady: true +--- + +import Since from '~/components/Since.astro'; +import { Steps } from '@astrojs/starlight/components'; + + +

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

+ +Enables experimental [Chrome DevTools workspace integration](https://developer.chrome.com/docs/devtools/workspaces) for the Astro dev server. + +This feature allows you to edit files directly in Chrome DevTools and have those changes reflected in your local file system via a connected workspace folder. This is useful for applying edits such as adjusting CSS values without leaving your browser tab. + +With this feature enabled, running `astro dev` will automatically configure a Chrome DevTools workspace for your project. Your project will then appear as an available [workspace source that you can connect](#connecting-your-project). Then, changes that you make in the "Sources" panel are automatically saved to your project source code. + +To enable this feature, add the experimental flag `chromeDevtoolsWorkspace` to your Astro config: + +```js title="astro.config.mjs" ins={4-6} +import { defineConfig } from 'astro/config'; + +export default defineConfig({ + experimental: { + chromeDevtoolsWorkspace: true, + }, +}); +``` + +## Connecting your project + +Astro will create the necessary configuration file to support Chrome DevTools workspaces. However, your project must also be [connected as a source](https://developer.chrome.com/docs/devtools/workspaces#manual-connection) to enable file saving. + + + +1. [Start the Astro dev server](/en/develop-and-build/#start-the-astro-dev-server) with the appropriate CLI command for your package manager. + +2. Navigate to your site preview (e.g. `http://localhost:4321/`) in Chrome and open DevTools. + +3. Under the **Sources** > **Workspaces** tab, you will find your Astro project folder. Click **Connect** to add your directory as a workspace. + + + +See the [Chrome DevTools workspace documentation](https://developer.chrome.com/docs/devtools/workspaces#connect) for more information. 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 deleted file mode 100644 index fc3e89f61d750..0000000000000 --- a/src/content/docs/en/reference/experimental-flags/raw-env-values.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -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/). diff --git a/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx b/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx new file mode 100644 index 0000000000000..a40a4d0594f92 --- /dev/null +++ b/src/content/docs/en/reference/experimental-flags/static-import-meta-env.mdx @@ -0,0 +1,88 @@ +--- +title: Experimental private meta environment variables inlining +sidebar: + label: Private meta environment variables inlining +i18nReady: true +--- + +import Since from '~/components/Since.astro' + +

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

+ +:::tip[Astro 6.0 preview] +The behavior enabled by this feature will become the default behavior in Astro 6.0. + +You may wish to add this flag whenever it is convenient to do so. You can start enjoying the benefits sooner and will avoid the need to update your project code for the next major Astro version. +::: + +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. This is the recommended way to use environment variables in Astro, as it allows you to easily see and manage whether your variables are public or secret, available on the client or only on the server at build time, and the data type of your values. + +However, you can still access your environment variables through `process.env` as well as `import.meta.env` directly if needed. This was the only way to use environment variables in Astro before `astro:env` was added in Astro 5.0, and its handling of `import.meta.env` includes some logic that was intended for earlier versions of Astro that is no longer necessary. + +The `experimental.staticImportMetaEnv` flag updates the behavior when accessing `import.meta.env` directly to align with [Vite's handling of environment variables](https://vite.dev/guide/env-and-mode.html#env-variables) and ensures that `import.meta.env` values are always inlined. + +Currently, non-public environment variables are replaced by a reference to `process.env`. Additionally, Astro may also convert the value type of your environment variables used through `import.meta.env`, which 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.staticImportMetaEnv` flag simplifies Astro's default behavior, making it easier to understand and use. Astro will no longer replace any `import.meta.env` environment variables with a `process.env` call, nor will it coerce values. + +To enable this feature, add the experimental flag in your Astro config: + +```js title="astro.config.mjs" ins={4-6} +import { defineConfig } from "astro/config" + +export default defineConfig({ + experimental: { + staticImportMetaEnv: true, + } +}) +``` + +## Usage + +Enabling this experimental flag will no longer convert string values into booleans or numbers, nor turn `import.meta.env` values into `process.env` calls. 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 this behavior by default, but you can opt in to the future behavior early using the `experimental.staticImportMetaEnv` flag and, if necessary, [updating your project](#updating-your-project) accordingly. + +### Updating your project + +If you were relying on 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 were relying on the transformation into `process.env`, 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.DB_PASSWORD; +const enabled: boolean = process.env.DB_PASSWORD; +``` + +You may also need to update types: + +```ts title="src/env.d.ts" del={3-4} ins={5,12-16} +interface ImportMetaEnv { + readonly PUBLIC_POKEAPI: string; + readonly DB_PASSWORD: string; + readonly ENABLED: boolean; + readonly ENABLED: string; +} + +interface ImportMeta { + readonly env: ImportMetaEnv; +} + +namespace NodeJS { + interface ProcessEnv { + DB_PASSWORD: string; + } +} +``` + +If you need more control over environment variables in Astro, we recommend you use [`astro:env`](/en/guides/environment-variables/). diff --git a/src/content/docs/fr/reference/experimental-flags/raw-env-values.mdx b/src/content/docs/fr/reference/experimental-flags/raw-env-values.mdx deleted file mode 100644 index 8fc2c6496cd1d..0000000000000 --- a/src/content/docs/fr/reference/experimental-flags/raw-env-values.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Valeurs brutes expérimentales des variables d'environnement -sidebar: - label: Variables d'environnement brutes -i18nReady: true ---- - -import Since from '~/components/Since.astro' - -

- -**Type :** `boolean`
-**Par défaut :** `false`
- -

- -Astro vous permet de configurer un [schéma avec sûreté du typage pour vos variables d'environnement](/fr/guides/environment-variables/#variables-denvironnement-avec-sûreté-du-typage), et convertit les variables importées via `astro:env` dans le type attendu. - -Cependant, Astro convertit également vos variables d'environnement utilisées via `import.meta.env` dans certains cas, ce qui peut empêcher l'accès à certaines valeurs telles que les chaînes de caractères `"true"` (qui est convertie en valeur booléenne) et `"1"` (qui est convertie en nombre). - -L'option `experimental.rawEnvValues` désactive la coercition des valeurs d'`import.meta.env` qui sont renseignées à partir de `process.env`, vous permettant d'utiliser la valeur brute. - -Pour désactiver la coercition d'Astro sur les valeurs utilisées via `import.meta.env`, définissez l'option `experimental.rawEnvValues` sur `true` dans votre configuration Astro : - -```js title="astro.config.mjs" ins={4-6} -import { defineConfig } from "astro/config" - -export default defineConfig({ - experimental: { - rawEnvValues: true, - } -}) -``` - -## Utilisation - -L'activation de cette option expérimentale ne convertira plus les valeurs de chaîne de caractères en booléens ou en nombres. Cela aligne le comportement de `import.meta.env` dans Astro avec celui de [Vite](https://vite.dev/guide/env-and-mode.html#env-variables). - -Dans une future version majeure, Astro passera à la non-contrainte des valeurs d'`import.meta.env` par défaut, mais vous pouvez opter pour le comportement futur plus tôt en utilisant l'option `experimental.rawEnvValues` et si nécessaire, [mettre à jour votre projet](#mise-à-jour-de-votre-projet) en conséquence. - -### Mise à jour de votre projet - -Si vous vous appuyiez sur cette coercition, vous devrez peut-être mettre à jour le code de votre projet pour l'appliquer manuellement : - -```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" -``` - -Si vous avez besoin de coercition dans Astro, nous vous recommandons d'utiliser [`astro:env`](/fr/guides/environment-variables/). diff --git a/src/content/docs/ko/reference/experimental-flags/raw-env-values.mdx b/src/content/docs/ko/reference/experimental-flags/raw-env-values.mdx deleted file mode 100644 index fd7895e7b14b3..0000000000000 --- a/src/content/docs/ko/reference/experimental-flags/raw-env-values.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: 실험적 원시 환경 변수 값 -sidebar: - label: 원시 환경 변수 -i18nReady: true ---- - -import Since from '~/components/Since.astro' - -

- -**타입:** `boolean`
-**기본값:** `false`
- -

- -Astro를 사용하면 [환경 변수에 대한 타입 안전 스키마](/ko/guides/environment-variables/#타입-안전-환경-변수)를 구성할 수 있으며, `astro:env`를 통해 가져온 변수를 예상 타입으로 변환할 수 있습니다. - -그러나 Astro는 경우에 따라 `import.meta.env`를 통해 사용되는 환경 변수도 변환하므로 문자열 `"true"` (부울 값으로 변환) 및 `"1"` (숫자로 변환)과 같은 일부 값에 액세스하지 못할 수도 있습니다. - -`experimental.rawEnvValues` 플래그를 사용하면 `process.env`에서 채워지는 `import.meta.env` 값의 강제 변환을 비활성화하여 원시 값을 사용할 수 있습니다. - -Astro가 `import.meta.env`를 통해 사용되는 값을 강제로 변환하지 못하게 하려면 Astro 구성에서 `experimental.rawEnvValues` 플래그를 `true`로 설정하세요. - -```js title="astro.config.mjs" ins={4-6} -import { defineConfig } from "astro/config" - -export default defineConfig({ - experimental: { - rawEnvValues: true, - } -}) -``` - -## 사용 - -이 실험적 플래그를 활성화하면 더 이상 문자열 값을 부울이나 숫자로 변환하지 않습니다. 이렇게 하면 Astro에서 `import.meta.env`의 동작이 [Vite](https://ko.vite.dev/guide/env-and-mode#env-variables)와 일치하게 됩니다. - -향후 주요 버전에서 Astro가 기본적으로 `import.meta.env` 값을 강제로 변환하지 않도록 전환할 예정이지만, `experimental.rawEnvValues` 플래그를 사용하여 향후 동작을 미리 선택하고 필요한 경우 그에 따라 [프로젝트를 업데이트](#프로젝트-업데이트)할 수 있습니다. - -### 프로젝트 업데이트 - -이 강제 변환에 의존하고 있다면 프로젝트 코드를 업데이트하여 수동으로 적용해야 할 수도 있습니다. - -```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" -``` - -Astro에서 강제 변환이 필요한 경우 [`astro:env`](/ko/guides/environment-variables/)를 사용하는 것이 좋습니다.