generated from florian-lefebvre/astro-integration-template
-
-
Notifications
You must be signed in to change notification settings - Fork 11
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Co-authored-by: Jacob Jenkins <[email protected]> Co-authored-by: Luiz Ferraz <[email protected]>
- Loading branch information
3 people
authored
Feb 10, 2024
1 parent
54d129f
commit f05c7ab
Showing
51 changed files
with
1,219 additions
and
438 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| --- | ||
| "astro-integration-kit": minor | ||
| --- | ||
|
|
||
| Introduces plugins and improves documentation |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| <div style="cursor:not-allowed"> | ||
| <div style="opacity: .5;pointer-events:none"> | ||
| <slot /> | ||
| </div> | ||
| </div> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,73 @@ | ||
| --- | ||
| title: createResolver | ||
| description: Allows resolving paths relatively to the integration folder easily. | ||
| --- | ||
|
|
||
| `createResolver` allows you to resolve paths relative to the integration folder easily. | ||
|
|
||
| ```ts title="integration/index.ts" "createResolver" "resolve" | ||
| import type { AstroIntegration } from "astro"; | ||
| import { createResolver } from "astro-integration-kit"; | ||
|
|
||
| export default function myIntegration(): AstroIntegration { | ||
| const { resolve } = createResolver(import.meta.url); | ||
|
|
||
| return { | ||
| name: "my-integration", | ||
| hooks: { | ||
| "astro:config:setup": ({ addDevToolbarApp }) => { | ||
| addDevToolbarApp(resolve("./plugin.ts")); | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Why should you use it? | ||
|
|
||
| We think it provides a better DX. Instead of having to do some back and forth between | ||
| your code and your `package.json` `exports` fields, you can just use some intuitive | ||
| relative paths! | ||
|
|
||
| ```json title="package.json" del={4} | ||
| { | ||
| "name": "package-name", | ||
| "exports": { | ||
| "pages/my-route.astro": "./src/pages/my-route.astro", | ||
| "plugin.ts": "./src/plugin.ts" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ```ts title="integration/index.ts" del={12,16} ins={5,13,17} | ||
| import type { AstroIntegration } from "astro"; | ||
| import { createResolver } from "astro-integration-kit"; | ||
|
|
||
| export default function myIntegration(): AstroIntegration { | ||
| const { resolve } = createResolver(import.meta.url); | ||
| return { | ||
| name: "my-integration", | ||
| hooks: { | ||
| "astro:config:setup": ({ injectRoute, addDevToolbarApp }) => { | ||
| injectRoute({ | ||
| pattern: "/my-route", | ||
| entrypoint: "package-name/pages/my-route.astro" | ||
| entrypoint: resolve("./pages/my-route.astro") | ||
| }) | ||
| addDevToolbarApp( | ||
| "package-name/plugin.ts" | ||
| resolve("./plugin.ts") | ||
| ) | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Usage | ||
|
|
||
| Always pass `import.meta.url` to `createResolver`! That's the equivalent of the | ||
| old `__filename`. This way, `resolve` will always create a valid path relatively, | ||
| no matter its location in `node_modules`, package managers madness etc | ||
|
|
||
| We recommend calling it in `setup` to easily access `resolve` in any hook. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,153 @@ | ||
| --- | ||
| title: defineIntegration | ||
| description: A powerful wrapper around the standard Astro Integrations API. It allows to provide extra hooks, functionality and best-practices when creating Astro Integrations. | ||
| --- | ||
| import Disabled from "~/components/Disabled.astro" | ||
| import { LinkCard } from '@astrojs/starlight/components'; | ||
|
|
||
| `defineIntegration` is a powerful wrapper around the standard Astro Integrations API. It allows to provide | ||
| extra hooks, functionality and best-practices when creating Astro Integrations. | ||
|
|
||
| ```ts title="my-integration/index.ts" "defineIntegration" | ||
| import { | ||
| createResolver, | ||
| defineIntegration, | ||
| defineOptions, | ||
| } from "astro-integration-kit"; | ||
| import { corePlugins } from "astro-integration-kit/plugins"; | ||
|
|
||
| type Options = { | ||
| foo?: string | undefined; | ||
| } | ||
|
|
||
| export default defineIntegration({ | ||
| name: "my-integration", | ||
| options: defineOptions<Options>({ foo: "bar" }), | ||
| plugins: [...corePlugins], | ||
| setup({ options }) { | ||
| const { resolve } = createResolver(import.meta.url); | ||
|
|
||
| return { | ||
| "astro:config:setup": ({ watchIntegration }) => { | ||
| watchIntegration(resolve()) | ||
| } | ||
| } | ||
| } | ||
| }) | ||
| ``` | ||
|
|
||
| ## Defining an integration | ||
|
|
||
| To define an integration, use the `defineIntegration` utility: | ||
|
|
||
| ```ts title="my-integration/index.ts" "defineIntegration" | ||
| import { defineIntegration } from "astro-integration-kit"; | ||
|
|
||
| export default defineIntegration({ | ||
| // ... | ||
| name: "my-integration" | ||
| }) | ||
| ``` | ||
|
|
||
| :::caution | ||
| Never pass generics manually to `defineIntegration` or it will break all the | ||
| TypeScript magic of options and plugins. | ||
| ::: | ||
|
|
||
| <Disabled> | ||
| <LinkCard | ||
| title="Authoring an integration (soon)" | ||
| description="Learn how to write an integration the right way using Astro Integration Kit." | ||
| href="#" | ||
| /> | ||
| </Disabled> | ||
|
|
||
| It accepts a few arguments, whose usage is explained in the sections below. | ||
|
|
||
| ## Handling options and defaults | ||
|
|
||
| `defineIntegration` accepts an `option` argument that you need to use with `defineOptions`. | ||
|
|
||
| ```ts title="my-integration/index.ts" "defineOptions" ins={3-5,9} | ||
| import { defineIntegration, defineOptions } from "astro-integration-kit"; | ||
|
|
||
| type Options = { | ||
| foo?: string | undefined; | ||
| } | ||
|
|
||
| export default defineIntegration({ | ||
| // ... | ||
| options: defineOptions<Options>({ foo: "bar" }) | ||
| }) | ||
| ``` | ||
|
|
||
| :::note | ||
| Really read the docs about `defineOptions` through the link below, there are limitations and stuff | ||
| you need to know about. | ||
| ::: | ||
|
|
||
| <LinkCard | ||
| title="Read more about defineOptions" | ||
| description="Allows defining an integration options while keeping the whole thing type-safe." | ||
| href="/core/define-options/" | ||
| /> | ||
|
|
||
| ## Using plugins | ||
|
|
||
| Plugins allow us (and you!) to make Astro Integration Kit really powerful. It allows to add arguments | ||
| to built-in hooks in a type-safe way. Get started by using our `corePlugins`: | ||
|
|
||
| ```ts title="my-integration/index.ts" ins={2,6} | ||
| import { defineIntegration } from "astro-integration-kit"; | ||
| import { corePlugins } from "astro-integration-kit/plugins"; | ||
|
|
||
| export default defineIntegration({ | ||
| // ... | ||
| plugins: [...corePlugins] | ||
| }) | ||
| ``` | ||
|
|
||
| Under the hood, those plugins define using `definePlugin` pass "metadata" as types thanks to generics. | ||
|
|
||
| <Disabled> | ||
| <LinkCard | ||
| title="Authoring a plugin (soon)" | ||
| description="Learn how to write an Astro Integration Kit plugin the right way." | ||
| href="#" | ||
| /> | ||
| </Disabled> | ||
|
|
||
| ## Adding the logic with `setup` | ||
|
|
||
| If you've written an integration before by returning an `AstroIntegration` from a function, it's exactly | ||
| the same with `setup`! This is where all the logic lives: | ||
|
|
||
| ```ts title="my-integration/index.ts" ins={5-7} | ||
| import { defineIntegration } from "astro-integration-kit"; | ||
|
|
||
| export default defineIntegration({ | ||
| // ... | ||
| setup() { | ||
| return {} | ||
| } | ||
| }) | ||
| ``` | ||
| It accepts an object with data from the integration definition: | ||
|
|
||
| ```ts title="my-integration/index.ts" "{ options, name }" | ||
| import { defineIntegration } from "astro-integration-kit"; | ||
|
|
||
| export default defineIntegration({ | ||
| // ... | ||
| setup({ options, name }) { | ||
| return {} | ||
| } | ||
| }) | ||
| ``` | ||
|
|
||
| In setup, you'll want to add any logic that is shared between any hook, for example: | ||
|
|
||
| - Calling `createResolver` | ||
| - Save the `config` from `astro:config:done` to be used in later hooks | ||
|
|
||
| It needs to return Astro hooks. |
Oops, something went wrong.