From 8f3f7d56da38a13ed0fc7db96872e7137f3d738e Mon Sep 17 00:00:00 2001 From: Florian Lefebvre Date: Mon, 5 Feb 2024 18:32:04 +0100 Subject: [PATCH] feat: work on docs --- docs/astro.config.ts | 8 +- docs/src/components/Disabled.astro | 5 + .../content/docs/core/define-integration.mdx | 120 ++++++++++++++++-- docs/src/content/docs/core/define-plugin.mdx | 9 +- .../content/docs/getting-started/usage.mdx | 17 ++- docs/src/content/docs/getting-started/why.mdx | 16 ++- docs/src/content/docs/utilities/add-dts.mdx | 6 + docs/tsconfig.json | 6 + 8 files changed, 153 insertions(+), 34 deletions(-) create mode 100644 docs/src/components/Disabled.astro diff --git a/docs/astro.config.ts b/docs/astro.config.ts index 3f866158..d7ebb988 100644 --- a/docs/astro.config.ts +++ b/docs/astro.config.ts @@ -51,7 +51,7 @@ export default defineConfig({ }, ], expressiveCode: { - themes: ["one-dark-pro", "starlight-light"] + themes: ["one-dark-pro", "starlight-light"], }, sidebar: [ { @@ -144,7 +144,7 @@ export default defineConfig({ ], }, { - label: `v${version} changelog`, + label: `v${version} changelog ↗`, link: `https://github.com/florian-lefebvre/astro-integration-kit/blob/main/package/CHANGELOG.md#${version.replaceAll( ".", "", @@ -152,10 +152,6 @@ export default defineConfig({ attrs: { target: "_blank", }, - badge: { - variant: "note", - text: "Latest", - }, }, ], lastUpdated: true, diff --git a/docs/src/components/Disabled.astro b/docs/src/components/Disabled.astro new file mode 100644 index 00000000..3e276b6a --- /dev/null +++ b/docs/src/components/Disabled.astro @@ -0,0 +1,5 @@ +
+
+ +
+
\ No newline at end of file diff --git a/docs/src/content/docs/core/define-integration.mdx b/docs/src/content/docs/core/define-integration.mdx index bd30782d..aee17cb9 100644 --- a/docs/src/content/docs/core/define-integration.mdx +++ b/docs/src/content/docs/core/define-integration.mdx @@ -2,6 +2,8 @@ title: defineIntegration description: Makes creating integrations easier, and adds a few goodies! --- +import Disabled from "~/components/Disabled.astro" +import { LinkCard } from '@astrojs/starlight/components'; `defineIntegration` makes creating integrations easier, and adds a few goodies! @@ -17,7 +19,7 @@ type Options = { foo?: string | undefined; } -export default defineIntegration<{ foo?: string }>({ +export default defineIntegration({ name: "my-integration", options: defineOptions({ foo: "bar" }), plugins: [...corePlugins], @@ -37,24 +39,116 @@ export default defineIntegration<{ foo?: string }>({ ### Defining an integration -- basic usage -- never pass generics directly -- link to guide +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. +::: + + + + + +It accepts a few arguments, whose usage is explained in the sections below. ### Handling options and defaults -- quick snippet -- alert type note: really read defineOptions docs, super important -- link to defineOptions +`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({ foo: "bar" }) +}) +``` + +:::note +Really read the docs about `defineOptions` through the link below, there are limitations and stuff +you need to know about. +::: + + ### Using plugins -- how they work -- corePlugins -- link to guide to learn how to author them +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. + + + + ### Adding the logic with `setup` -- arguments passed to setup -- what to do in setup -- what to return \ No newline at end of file +If you've written an integration before by returning an `AstroIntegration` from a function, that 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. \ No newline at end of file diff --git a/docs/src/content/docs/core/define-plugin.mdx b/docs/src/content/docs/core/define-plugin.mdx index 12131095..79d39206 100644 --- a/docs/src/content/docs/core/define-plugin.mdx +++ b/docs/src/content/docs/core/define-plugin.mdx @@ -5,4 +5,11 @@ description: Allows defining a type-safe plugin that can be used in defineIntegr Allows defining a type-safe plugin that can be used in `defineIntegration`. -WIP \ No newline at end of file +- Quick snippet +- Limitations + - Overrides + - One plugin per hook + - Can't be built on other plugins +- Warning: advanced use-case +- Integrate with AIK +- AIK uses this under the hood, have a look at our source for examples \ No newline at end of file diff --git a/docs/src/content/docs/getting-started/usage.mdx b/docs/src/content/docs/getting-started/usage.mdx index c2c9fcf2..21ea80f8 100644 --- a/docs/src/content/docs/getting-started/usage.mdx +++ b/docs/src/content/docs/getting-started/usage.mdx @@ -2,6 +2,7 @@ title: Usage description: Learn how to use astro-integration-kit in your project. --- +import Disabled from "~/components/Disabled.astro" import { LinkCard, Tabs, TabItem } from '@astrojs/starlight/components'; Astro Integration Kit can be used in 2 ways: as **extended hooks** or as **standalone utilities**. @@ -64,15 +65,13 @@ or one by one as needed. This allows other developers to easily add their own plugins. -
-
- -
-
+ + + ### Defining an integration diff --git a/docs/src/content/docs/getting-started/why.mdx b/docs/src/content/docs/getting-started/why.mdx index 7ccb657e..66aacae9 100644 --- a/docs/src/content/docs/getting-started/why.mdx +++ b/docs/src/content/docs/getting-started/why.mdx @@ -3,19 +3,25 @@ title: Why should you use Astro Integration Kit? description: Learn why you should use Astro Integration Kit to build your next Astro Integration. --- -Astro Integration Kit is a community-driven effort to improve the power, flexibility, and, most importantly, developer experience of creating Astro Integrations. +Astro Integration Kit is a **community-driven effort** to improve the power, flexibility, and, most importantly, +developer experience of creating Astro Integrations. -We are creating the Astro Integration Kit because we want to create a robust, battle-tested suite of tools to make creating Astro integrations easier in the hopes that one day, this will become part of the core Astro framework. +We are creating the Astro Integration Kit because we want to create a robust, battle-tested suite of tools to make +creating Astro integrations easier in the hopes that one day, this will become part of the core Astro framework. We constantly gather feedback from the entire community, from first-time integration builders to the seasoned Astro Core team. -Astro Integration Kit is currently an experimental technology that's still subject to changes as we solidify the APIs. However, it was built from techniques used in production-level integrations across the Astro Ecosystem. +Astro Integration Kit is currently an **experimental technology** that's still subject to changes as we solidify the APIs. +However, it was built from techniques used in production-level integrations across the Astro Ecosystem. -Integrations typically require quite a low-level knowledge of Astro and Vite to be made successfully. So, Astro Integration Kit abstracts a lot of low-level implementation into easy-to-use utilities. Things such as Vite Virtual Modules or creating Typescript Declaration files for your users. +Integrations typically require quite a low-level knowledge of Astro and Vite to be made successfully. So, Astro Integration +Kit abstracts a lot of low-level implementation into easy-to-use utilities. Things such as Vite Virtual Modules or creating +Typescript Declaration files for your users. Small utilities allow you to adhere to best practices with the minimum amount of code. -Once we have a standard way of creating Astro Integrations, we can create content and guides much more easily using well-documented utilities, enabling more people to create more advanced integrations. +Once we have a standard way of creating Astro Integrations, we can create content and guides much more easily using well-documented +utilities, enabling more people to create more advanced integrations. :::note We are constantly looking for feedback and contributions from the community. Whether it's contributing code, ideas or suggestions; feel free to create an issue on [our GitHub repository](https://github.com/florian-lefebvre/astro-integration-kit). diff --git a/docs/src/content/docs/utilities/add-dts.mdx b/docs/src/content/docs/utilities/add-dts.mdx index 051b5f9a..57a41e3c 100644 --- a/docs/src/content/docs/utilities/add-dts.mdx +++ b/docs/src/content/docs/utilities/add-dts.mdx @@ -7,6 +7,12 @@ import { Tabs, TabItem } from '@astrojs/starlight/components'; `addDts` allows you to inject a `.d.ts` file into the user's project. It will create a file inside `.astro` and reference it from `src/env.d.ts`. For example: +- quick description +- quick snippet +- usage +- works well with `addVirtualImport` +- tip: using a template file with placeholders + ```ts title="my-integration/index.ts" "addDts" diff --git a/docs/tsconfig.json b/docs/tsconfig.json index 0be1a571..54110d9f 100644 --- a/docs/tsconfig.json +++ b/docs/tsconfig.json @@ -1,4 +1,10 @@ { "extends": "astro/tsconfigs/strict", + "compilerOptions": { + "baseUrl": ".", + "paths": { + "~/*": ["./src/*"] + } + }, "exclude": ["dist"] } \ No newline at end of file