From dbf3ce4c6bba6ef0f9cd7ac52a8af1d165c87242 Mon Sep 17 00:00:00 2001 From: Florian Lefebvre Date: Mon, 5 Aug 2024 16:42:19 +0200 Subject: [PATCH 1/9] feat: update integrations api reference --- .../en/reference/integrations-reference.mdx | 44 ++++++++++++++++--- 1 file changed, 39 insertions(+), 5 deletions(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 2df1ef4922f98..3e6af7e644a85 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -33,10 +33,15 @@ interface AstroIntegration { addMiddleware: (middleware: AstroIntegrationMiddleware) => void; addDevToolbarApp: (pluginEntrypoint: string) => void; injectScript: (stage: InjectedScriptStage, content: string) => void; - injectRoute: ({ pattern: string, entrypoint: string }) => void; + injectRoute: (injectedRoute: { pattern: string, entrypoint: string }) => void; logger: AstroIntegrationLogger; }) => void | Promise; - 'astro:config:done'?: (options: { config: AstroConfig; setAdapter: (adapter: AstroAdapter) => void; logger: AstroIntegrationLogger; }) => void | Promise; + 'astro:config:done'?: (options: { + config: AstroConfig; + setAdapter: (adapter: AstroAdapter) => void; + injectTypes: (injectedType: { filename: string; content: string }) => URL; + logger: AstroIntegrationLogger; + }) => void | Promise; 'astro:server:setup'?: (options: { server: vite.ViteDevServer; logger: AstroIntegrationLogger; }) => void | Promise; 'astro:server:start'?: (options: { address: AddressInfo; logger: AstroIntegrationLogger; }) => void | Promise; 'astro:server:done'?: (options: { logger: AstroIntegrationLogger; }) => void | Promise; @@ -385,9 +390,14 @@ The **`stage`** denotes how this script (the `content`) should be inserted. Some **When:** After the Astro config has resolved and other integrations have run their `astro:config:setup` hooks. **Why:** To retrieve the final config for use in other hooks. - +TODO: ```js -'astro:config:done'?: (options: { config: AstroConfig }) => void | Promise; +'astro:config:done'?: (options: { + config: AstroConfig; + setAdapter: (adapter: AstroAdapter) => void; + injectTypes: (injectedType: { filename: string; content: string }) => URL; + logger: AstroIntegrationLogger; +}) => void | Promise; ``` #### `config` option @@ -396,6 +406,28 @@ The **`stage`** denotes how this script (the `content`) should be inserted. Some A read-only copy of the user-supplied [Astro config](/en/reference/configuration-reference/). This is resolved _after_ other integrations have run. +#### `setAdapter` option + +**Type:** `(adapter: AstroAdapter) => void;` + +Makes the integration an adapter. Read more in the [adapter API](/en/reference/adapter-reference/). + +#### `injectTypes` options + +**Type:** `(injectedType: { filename: string; content: string }) => URL` + +Allows you to inject types easily in your user's project. `filename` must ends with `".d.ts"` and `content` must be valid TypeScript (it will be formatted). + +Under the hood, it will create a file at `/.astro/integrations//.d.ts` and create references to it. `injectTypes` returns a URL to the normalized path. + +```ts +const path = injectTypes({ + filename: "types.d.ts", + content: "declare module 'virtual:integration' {}" +}) +console.log(path) // URL +``` + ### `astro:server:setup` **Previous hook:** [`astro:config:done`](#astroconfigdone) @@ -745,4 +777,6 @@ integrations: [ ## Community Resources - [Build your own Astro Integrations](https://www.freecodecamp.org/news/how-to-use-the-astro-ui-framework/#chapter-8-build-your-own-astro-integrations-1) - by Emmanuel Ohans on FreeCodeCamp -- [Astro Integration Template](https://github.com/florian-lefebvre/astro-integration-template) - by Florian Lefebvre on GitHub +- [Astro Integration Template](https://github.com/florian-lefebvre/astro-integration-template) - by Florian Lefebvre on GitHubimport type { log } from 'console' +import type { log } from 'console' + From 86788f7686452cfe8fba94a1b3e604dff09c304d Mon Sep 17 00:00:00 2001 From: Florian Lefebvre Date: Mon, 5 Aug 2024 16:46:57 +0200 Subject: [PATCH 2/9] fix --- src/content/docs/en/reference/integrations-reference.mdx | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 3e6af7e644a85..334cfacd14b3d 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -390,7 +390,7 @@ The **`stage`** denotes how this script (the `content`) should be inserted. Some **When:** After the Astro config has resolved and other integrations have run their `astro:config:setup` hooks. **Why:** To retrieve the final config for use in other hooks. -TODO: + ```js 'astro:config:done'?: (options: { config: AstroConfig; @@ -420,7 +420,7 @@ Allows you to inject types easily in your user's project. `filename` must ends w Under the hood, it will create a file at `/.astro/integrations//.d.ts` and create references to it. `injectTypes` returns a URL to the normalized path. -```ts +```js const path = injectTypes({ filename: "types.d.ts", content: "declare module 'virtual:integration' {}" @@ -777,6 +777,4 @@ integrations: [ ## Community Resources - [Build your own Astro Integrations](https://www.freecodecamp.org/news/how-to-use-the-astro-ui-framework/#chapter-8-build-your-own-astro-integrations-1) - by Emmanuel Ohans on FreeCodeCamp -- [Astro Integration Template](https://github.com/florian-lefebvre/astro-integration-template) - by Florian Lefebvre on GitHubimport type { log } from 'console' -import type { log } from 'console' - +- [Astro Integration Template](https://github.com/florian-lefebvre/astro-integration-template) - by Florian Lefebvre on GitHub From 097b490d3c0eafe5c636e318ecd202152545e696 Mon Sep 17 00:00:00 2001 From: Florian Lefebvre Date: Mon, 5 Aug 2024 16:53:16 +0200 Subject: [PATCH 3/9] feat: update mentions to sync and env.d.ts --- .../docs/en/guides/integrations-guide/cloudflare.mdx | 2 +- src/content/docs/en/guides/integrations-guide/netlify.mdx | 1 - src/content/docs/en/guides/integrations-guide/vercel.mdx | 1 - src/content/docs/en/guides/middleware.mdx | 3 ++- src/content/docs/en/guides/typescript.mdx | 2 +- src/content/docs/en/install-and-setup.mdx | 7 ------- src/content/docs/en/reference/cli-reference.mdx | 3 ++- 7 files changed, 6 insertions(+), 13 deletions(-) diff --git a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx index 0d0ca0dca70b9..f480874474ecd 100644 --- a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx +++ b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx @@ -289,7 +289,7 @@ You can create a pnpm script to run `wrangler types` automatically before other You can type the `runtime` object using `Runtime`: ```ts title="src/env.d.ts" -/// +/// type Runtime = import('@astrojs/cloudflare').Runtime; diff --git a/src/content/docs/en/guides/integrations-guide/netlify.mdx b/src/content/docs/en/guides/integrations-guide/netlify.mdx index 3f6542754c561..ef7976b77934b 100644 --- a/src/content/docs/en/guides/integrations-guide/netlify.mdx +++ b/src/content/docs/en/guides/integrations-guide/netlify.mdx @@ -112,7 +112,6 @@ If you're using TypeScript, you can get proper typings by updating `src/env.d.ts ```ts title="src/env.d.ts" /// -/// type NetlifyLocals = import('@astrojs/netlify').NetlifyLocals diff --git a/src/content/docs/en/guides/integrations-guide/vercel.mdx b/src/content/docs/en/guides/integrations-guide/vercel.mdx index a287e3753a9fc..bb0ee58b2387a 100644 --- a/src/content/docs/en/guides/integrations-guide/vercel.mdx +++ b/src/content/docs/en/guides/integrations-guide/vercel.mdx @@ -420,7 +420,6 @@ The edge middleware has access to Vercel's [`RequestContext`](https://vercel.com ```ts /// -/// type EdgeLocals = import('@astrojs/vercel').EdgeLocals diff --git a/src/content/docs/en/guides/middleware.mdx b/src/content/docs/en/guides/middleware.mdx index 60110a09d4d3c..7dd4e572013d4 100644 --- a/src/content/docs/en/guides/middleware.mdx +++ b/src/content/docs/en/guides/middleware.mdx @@ -141,7 +141,8 @@ export const onRequest = (context, next) => { To type the information inside `Astro.locals`, which gives you autocompletion inside `.astro` files and middleware code, declare a global namespace in the `env.d.ts` file: ```ts title="src/env.d.ts" -/// +/// + declare namespace App { interface Locals { user: { diff --git a/src/content/docs/en/guides/typescript.mdx b/src/content/docs/en/guides/typescript.mdx index fab2911c48190..40a22706b3910 100644 --- a/src/content/docs/en/guides/typescript.mdx +++ b/src/content/docs/en/guides/typescript.mdx @@ -30,7 +30,7 @@ To inherit from one of the templates, use [the `extends` setting](https://www.ty Additionally, our templates include an `env.d.ts` file inside the `src` folder to provide [Vite's client types](https://vitejs.dev/guide/features.html#client-types) to your project: ```typescript title="env.d.ts" -/// +/// ``` If you are not using VSCode, you can install the [Astro TypeScript plugin](https://www.npmjs.com/package/@astrojs/ts-plugin) to support importing `.astro` files from `.ts` files (which can be useful for re-exporting). diff --git a/src/content/docs/en/install-and-setup.mdx b/src/content/docs/en/install-and-setup.mdx index 043fde614e462..573f3a682345b 100644 --- a/src/content/docs/en/install-and-setup.mdx +++ b/src/content/docs/en/install-and-setup.mdx @@ -398,12 +398,6 @@ If you prefer not to use our automatic `create astro` CLI tool, you can set up y } ``` - Finally, create `src/env.d.ts` to let TypeScript know about ambient types available in an Astro project: - - ```ts title="src/env.d.ts" - /// - ``` - Read Astro's [TypeScript setup guide](/en/guides/typescript/#setup) for more information. 7. Next Steps @@ -417,7 +411,6 @@ If you prefer not to use our automatic `create astro` CLI tool, you can set up y - src/ - pages/ - index.astro - - env.d.ts - astro.config.mjs - package-lock.json or `yarn.lock`, `pnpm-lock.yaml`, etc. - package.json diff --git a/src/content/docs/en/reference/cli-reference.mdx b/src/content/docs/en/reference/cli-reference.mdx index 83d17170db318..c07d10e6f18d3 100644 --- a/src/content/docs/en/reference/cli-reference.mdx +++ b/src/content/docs/en/reference/cli-reference.mdx @@ -68,7 +68,7 @@ Commands docs Open documentation in your web browser. info List info about your current Astro setup. preview Preview your build locally. - sync Generate content collection types. + sync Generates TypeScript types for all Astro modules. preferences Configure user preferences. telemetry Configure telemetry settings. @@ -267,6 +267,7 @@ Running `astro dev`, `astro build` or `astro check` will run the `sync` command Generates TypeScript types for all Astro modules. This sets up a [`src/env.d.ts` file](/en/guides/typescript/#setup) for type inferencing, and defines modules for features that rely on generated types: - The `astro:content` module for the [Content Collections API](/en/guides/content-collections/). - The `astro:db` module for [Astro DB](/en/guides/astro-db/). +- The `astro:env` module for [experimental Astro Env](/en/reference/configuration-reference/#experimentalenv). ## `astro add` From 824ca01eb9a9698d0de1e1c799242565271d1bf2 Mon Sep 17 00:00:00 2001 From: Florian Lefebvre Date: Mon, 5 Aug 2024 16:56:10 +0200 Subject: [PATCH 4/9] feat: add since --- src/content/docs/en/reference/integrations-reference.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 334cfacd14b3d..b00b236a5b606 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -414,6 +414,8 @@ Makes the integration an adapter. Read more in the [adapter API](/en/reference/a #### `injectTypes` options +

+ **Type:** `(injectedType: { filename: string; content: string }) => URL` Allows you to inject types easily in your user's project. `filename` must ends with `".d.ts"` and `content` must be valid TypeScript (it will be formatted). From 644e56bdd24481e334b9579298275d4cd908c0e0 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Tue, 13 Aug 2024 08:17:51 -0300 Subject: [PATCH 5/9] Update src/content/docs/en/reference/integrations-reference.mdx --- src/content/docs/en/reference/integrations-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index b00b236a5b606..434242e37763d 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -418,7 +418,7 @@ Makes the integration an adapter. Read more in the [adapter API](/en/reference/a **Type:** `(injectedType: { filename: string; content: string }) => URL` -Allows you to inject types easily in your user's project. `filename` must ends with `".d.ts"` and `content` must be valid TypeScript (it will be formatted). +Allows you to inject types into your user's project. `filename` must ends with `".d.ts"` and `content` must be valid TypeScript. Under the hood, it will create a file at `/.astro/integrations//.d.ts` and create references to it. `injectTypes` returns a URL to the normalized path. From 3cfda28256d09dead2c7ab03c084de480cb08e6e Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Tue, 13 Aug 2024 08:18:16 -0300 Subject: [PATCH 6/9] Update src/content/docs/en/reference/integrations-reference.mdx --- src/content/docs/en/reference/integrations-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 434242e37763d..8fa2387abde84 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -420,7 +420,7 @@ Makes the integration an adapter. Read more in the [adapter API](/en/reference/a Allows you to inject types into your user's project. `filename` must ends with `".d.ts"` and `content` must be valid TypeScript. -Under the hood, it will create a file at `/.astro/integrations//.d.ts` and create references to it. `injectTypes` returns a URL to the normalized path. + This will create a file at `/.astro/integrations//.d.ts` and create references to it. `injectTypes` returns a URL to the normalized path. ```js const path = injectTypes({ From adfed11c41870bafdcad9d1c6881c3017fa6c05c Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Tue, 13 Aug 2024 08:24:18 -0300 Subject: [PATCH 7/9] Update src/content/docs/en/reference/integrations-reference.mdx --- src/content/docs/en/reference/integrations-reference.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 8fa2387abde84..4f7b937dd0920 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -418,7 +418,11 @@ Makes the integration an adapter. Read more in the [adapter API](/en/reference/a **Type:** `(injectedType: { filename: string; content: string }) => URL` -Allows you to inject types into your user's project. `filename` must ends with `".d.ts"` and `content` must be valid TypeScript. +Allows you to inject types into your user's project by adding a new a `*.d.ts` file. + +The `filename` property will be used to generate a file at `/.astro/integrations//.d.ts` and must end with `".d.ts"` + +The `content` property will create the body of the file, and must be valid TypeScript. This will create a file at `/.astro/integrations//.d.ts` and create references to it. `injectTypes` returns a URL to the normalized path. From 7b990efbc47e58d260bb9e559b6ebb0cfd00a606 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Tue, 13 Aug 2024 08:26:39 -0300 Subject: [PATCH 8/9] Update src/content/docs/en/reference/integrations-reference.mdx --- src/content/docs/en/reference/integrations-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 4f7b937dd0920..09ff6714bba7f 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -424,7 +424,7 @@ The `filename` property will be used to generate a file at `/.astro/integrations The `content` property will create the body of the file, and must be valid TypeScript. - This will create a file at `/.astro/integrations//.d.ts` and create references to it. `injectTypes` returns a URL to the normalized path. +Additionally, `injectTypes()` returns a URL to the normalized path so you can/to allow for... ```js const path = injectTypes({ From 168a851df9aa794a8d11dcacf6567280d6e78652 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Tue, 13 Aug 2024 10:24:54 -0300 Subject: [PATCH 9/9] Apply suggestions from Florian code review Co-authored-by: Florian Lefebvre --- src/content/docs/en/reference/cli-reference.mdx | 1 + src/content/docs/en/reference/integrations-reference.mdx | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/reference/cli-reference.mdx b/src/content/docs/en/reference/cli-reference.mdx index c07d10e6f18d3..ca7e42d76f944 100644 --- a/src/content/docs/en/reference/cli-reference.mdx +++ b/src/content/docs/en/reference/cli-reference.mdx @@ -268,6 +268,7 @@ Generates TypeScript types for all Astro modules. This sets up a [`src/env.d.ts` - The `astro:content` module for the [Content Collections API](/en/guides/content-collections/). - The `astro:db` module for [Astro DB](/en/guides/astro-db/). - The `astro:env` module for [experimental Astro Env](/en/reference/configuration-reference/#experimentalenv). +- The `astro:actions` module for [experimental Astro Actions](/en/reference/configuration-reference/#experimentalactions) ## `astro add` diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 09ff6714bba7f..99f3089952fb5 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -420,11 +420,11 @@ Makes the integration an adapter. Read more in the [adapter API](/en/reference/a Allows you to inject types into your user's project by adding a new a `*.d.ts` file. -The `filename` property will be used to generate a file at `/.astro/integrations//.d.ts` and must end with `".d.ts"` +The `filename` property will be used to generate a file at `/.astro/integrations//.d.ts` and must end with `".d.ts"`. The `content` property will create the body of the file, and must be valid TypeScript. -Additionally, `injectTypes()` returns a URL to the normalized path so you can/to allow for... +Additionally, `injectTypes()` returns a URL to the normalized path so you can overwrite its content later on, or manipulate it in any way you want. ```js const path = injectTypes({