From e127632c0289be36d8c8e806597a15a4c516d7fe Mon Sep 17 00:00:00 2001 From: Stijn Van Hulle Date: Thu, 23 Nov 2023 19:16:44 +0100 Subject: [PATCH] docs: rework docs for v2 --- docs/.vitepress/config.ts | 312 +++++++++++----- docs/config/hooks.md | 54 +++ docs/config/input.md | 60 +++ docs/config/name.md | 57 +++ docs/config/output.md | 83 +++++ docs/config/overview.md | 57 +++ docs/config/plugins.md | 39 ++ docs/config/root.md | 31 ++ docs/examples/advanced.md | 2 +- docs/examples/client.md | 2 +- docs/examples/faker.md | 2 +- docs/examples/msw.md | 2 +- docs/examples/simple.md | 2 +- docs/examples/swr.md | 2 +- .../examples/tanstack-query/react-query-v5.md | 2 +- docs/examples/tanstack-query/react-query.md | 2 +- docs/examples/tanstack-query/solid-query.md | 2 +- docs/examples/tanstack-query/svelte-query.md | 2 +- docs/examples/tanstack-query/vue-query-v5.md | 2 +- docs/examples/tanstack-query/vue-query.md | 2 +- docs/examples/typescript.md | 2 +- docs/examples/zod.md | 2 +- docs/guide/cli.md | 145 ++++++++ docs/guide/configure.md | 229 ++++-------- docs/guide/introduction.md | 73 +--- docs/guide/options.md | 346 ------------------ docs/guide/quick-start.md | 83 +---- docs/index.md | 8 +- docs/plugins/development/core.md | 8 + docs/plugins/development/system.md | 8 + .../template.md} | 58 ++- docs/plugins/overview.md | 22 ++ docs/plugins/react/components/text.md | 4 +- docs/public/feature/react.svg | 1 + docs/readme.md | 2 +- docs/reference/overview.md | 8 + packages/cli/src/utils/getCosmiConfig.ts | 4 +- 37 files changed, 944 insertions(+), 776 deletions(-) create mode 100644 docs/config/hooks.md create mode 100644 docs/config/input.md create mode 100644 docs/config/name.md create mode 100644 docs/config/output.md create mode 100644 docs/config/overview.md create mode 100644 docs/config/plugins.md create mode 100644 docs/config/root.md create mode 100644 docs/guide/cli.md delete mode 100644 docs/guide/options.md create mode 100644 docs/plugins/development/core.md create mode 100644 docs/plugins/development/system.md rename docs/plugins/{introduction.md => development/template.md} (56%) create mode 100644 docs/plugins/overview.md create mode 100644 docs/public/feature/react.svg create mode 100644 docs/reference/overview.md diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 92e3e4318..c523205df 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -24,40 +24,69 @@ const guideSidebar = [ text: 'Installation', link: '/guide/installation', }, - // { - // text: 'Comparison under construction', - // link: '/comparison', - // }, + { + text: 'Configure', + link: '/guide/configure', + }, + { + text: 'CLI', + link: '/guide/cli', + }, { text: 'Quick start', link: '/guide/quick-start', }, ], }, + { - text: 'Configuration', + text: 'Tutorials', + collapsed: false, items: [ { - text: 'Options', - link: '/guide/options', + text: 'Basic', + link: '/guide/tutorial/basic', }, { - text: 'Configuring Kubb', - link: '/guide/configure', + text: 'Templates new', + link: '/guide/tutorial/templates', }, ], }, +] + +const configSidebar = [ { - text: 'Tutorials', + text: 'Overview', + link: '/config/overview', + }, + { + text: 'Options', collapsed: false, items: [ { - text: 'Basic tutorial', - link: '/guide/tutorial/basic', + text: 'name', + link: '/config/name', }, { - text: 'Templates tutorial new', - link: '/guide/tutorial/templates', + text: 'root', + link: '/config/root', + }, + { + text: 'input', + link: '/config/input', + }, + { + text: 'output', + link: '/config/output', + }, + { + text: 'plugins', + link: '/config/plugins', + }, + { + text: 'hooks', + link: '/config/hooks', }, ], }, @@ -65,13 +94,32 @@ const guideSidebar = [ const referenceSidebar = [ { - text: 'Plugins', + text: 'Overview', + link: '/reference/overview', + }, + { + text: 'FileManager', + link: '/reference/fileManager', + }, + { + text: 'PluginManager', + link: '/reference/pluginManager', + }, + { + text: 'Templates ', + link: '/reference/templates', + }, +] + +const pluginsSidebar = [ + { + text: 'Overview', + link: '/plugins/overview', + }, + { + text: 'Internal plugins', collapsed: false, items: [ - { - text: 'Introduction', - link: '/plugins/introduction', - }, { text: '@kubb/core', collapsed: true, @@ -87,56 +135,6 @@ const referenceSidebar = [ text: '@kubb/cli', link: '/plugins/cli', }, - { - text: 'Swagger plugins', - collapsed: true, - items: [ - { text: '@kubb/swagger', link: '/plugins/swagger' }, - { - text: '@kubb/swagger-client', - collapsed: true, - link: '/plugins/swagger-client/', - items: [ - { - text: 'globals.d.ts', - link: '/plugins/swagger-client/globals', - }, - { - text: 'client', - link: '/plugins/swagger-client/client', - }, - ], - }, - { - text: '@kubb/swagger-ts', - link: '/plugins/swagger-ts', - }, - { - text: '@kubb/swagger-zod', - link: '/plugins/swagger-zod', - }, - { - text: '@kubb/swagger-zodios', - link: '/plugins/swagger-zodios', - }, - { - text: '@kubb/swagger-tanstack-query v5 support', - link: '/plugins/swagger-tanstack-query', - }, - { - text: '@kubb/swagger-swr', - link: '/plugins/swagger-swr', - }, - { - text: '@kubb/swagger-faker', - link: '/plugins/swagger-faker', - }, - { - text: '@kubb/swagger-msw v2 support', - link: '/plugins/swagger-msw', - }, - ], - }, { text: '@kubb/parser', link: '/plugins/parser', @@ -178,20 +176,70 @@ const referenceSidebar = [ ], }, { - text: 'API under construction', + text: 'Swagger plugins', + collapsed: false, + items: [ + { text: '@kubb/swagger', link: '/plugins/swagger' }, + { + text: '@kubb/swagger-client', + collapsed: true, + link: '/plugins/swagger-client/', + items: [ + { + text: 'globals.d.ts', + link: '/plugins/swagger-client/globals', + }, + { + text: 'client', + link: '/plugins/swagger-client/client', + }, + ], + }, + { + text: '@kubb/swagger-ts', + link: '/plugins/swagger-ts', + }, + { + text: '@kubb/swagger-zod', + link: '/plugins/swagger-zod', + }, + { + text: '@kubb/swagger-zodios', + link: '/plugins/swagger-zodios', + }, + { + text: '@kubb/swagger-tanstack-query v5 support', + link: '/plugins/swagger-tanstack-query', + }, + { + text: '@kubb/swagger-swr', + link: '/plugins/swagger-swr', + }, + { + text: '@kubb/swagger-faker', + link: '/plugins/swagger-faker', + }, + { + text: '@kubb/swagger-msw v2 support', + link: '/plugins/swagger-msw', + }, + ], + }, + { + text: 'Development', collapsed: false, items: [ { - text: 'FileManager', - link: '/reference/fileManager', + text: 'Plugin system', + link: '/plugins/development/system', }, { - text: 'PluginManager', - link: '/reference/pluginManager', + text: 'Plugin core', + link: '/plugins/development/core', }, { - text: 'Templates ', - link: '/reference/templates', + text: 'Plugin template', + link: '/plugins/development/template', }, ], }, @@ -268,6 +316,89 @@ const blogSidebar = [ }, ] +const pluginsMenu = [ + { + text: 'Overview', + link: '/plugins/overview', + }, + { + text: 'Internal plugins', + items: [ + { + text: '@kubb/core', + link: '/plugins/core/', + }, + { + text: '@kubb/cli', + link: '/plugins/cli', + }, + { + text: '@kubb/parser', + link: '/plugins/parser', + }, + { + text: '@kubb/react', + link: '/plugins/react/', + }, + ], + }, + { + text: 'Swagger plugins', + items: [ + { text: '@kubb/swagger', link: '/plugins/swagger' }, + { + text: '@kubb/swagger-client', + link: '/plugins/swagger-client/', + }, + { + text: '@kubb/swagger-ts', + link: '/plugins/swagger-ts', + }, + { + text: '@kubb/swagger-zod', + link: '/plugins/swagger-zod', + }, + { + text: '@kubb/swagger-zodios', + link: '/plugins/swagger-zodios', + }, + { + text: '@kubb/swagger-tanstack-query', + link: '/plugins/swagger-tanstack-query', + }, + { + text: '@kubb/swagger-swr', + link: '/plugins/swagger-swr', + }, + { + text: '@kubb/swagger-faker', + link: '/plugins/swagger-faker', + }, + { + text: '@kubb/swagger-msw', + link: '/plugins/swagger-msw', + }, + ], + }, + { + text: 'Development', + items: [ + { + text: 'Plugin system', + link: '/plugins/development/system', + }, + { + text: 'Plugin core', + link: '/plugins/development/core', + }, + { + text: 'Plugin template', + link: '/plugins/development/template', + }, + ], + }, +] + // https://vitepress.dev/reference/site-config export default defineConfig({ lang: 'en-UK', @@ -326,13 +457,22 @@ export default defineConfig({ provider: 'local', }, nav: [ - { text: 'Guide', link: '/guide/introduction' }, - { text: 'Reference', link: '/plugins/introduction' }, - { text: 'Examples', link: '/examples/typescript' }, - { text: 'Playground', link: '/playground' }, + { text: 'Guide', link: '/guide/introduction', activeMatch: 'guide' }, + { text: 'Config', link: '/config/overview', activeMatch: 'config' }, { - text: 'Blog', - link: '/blog/v2', + text: 'Plugins', + activeMatch: 'plugins', + items: [ + ...pluginsMenu, + ], + }, + { text: 'Reference', link: '/reference/overview', activeMatch: 'reference' }, + { + text: 'Try Out', + items: [ + { text: 'Examples', link: '/examples/typescript', activeMatch: 'examples' }, + { text: 'Playground', link: '/playground' }, + ], }, { text: `v${version}`, @@ -342,6 +482,10 @@ export default defineConfig({ link: 'https://kubb.dev', target: '_blank', }, + { + text: 'Blog', + link: '/blog/v2', + }, { text: 'Releases', link: 'https://github.com/kubb-project/kubb/releases', @@ -374,9 +518,9 @@ export default defineConfig({ pattern: 'https://github.com/kubb-project/kubb/edit/main/docs/src/:path', }, sidebar: { - '/configuration': guideSidebar, + '/config': configSidebar, '/guide': guideSidebar, - '/plugins': referenceSidebar, + '/plugins': pluginsSidebar, '/reference': referenceSidebar, '/examples': examplesSidebar, '/blog': blogSidebar, diff --git a/docs/config/hooks.md b/docs/config/hooks.md new file mode 100644 index 000000000..9fa5490a4 --- /dev/null +++ b/docs/config/hooks.md @@ -0,0 +1,54 @@ +--- +layout: doc + +title: Config +outline: deep +--- + +# hooks + +Hooks that will be called when a specific action is triggered in Kubb. + +## hooks.done + +Hook that will be triggered at the end of Kubb's generation.
+Useful for running Prettier or ESLint to format/lint your code. + +::: info +Type: `string | string[]`
+ +::: code-group + +```typescript [kubb.config.ts] +import { defineConfig } from '@kubb/core' + +export default defineConfig({ + hooks: { + done: ['npx prettier --write .'], + }, + input: { + path: './petStore.yaml', + }, + output: { + path: './src/gen', + }, +}) +``` + +```typescript [kubb.config.ts] +import { defineConfig } from '@kubb/core' + +export default defineConfig({ + hooks: { + done: 'npx prettier --write .', + }, + input: { + path: './petStore.yaml', + }, + output: { + path: './src/gen', + }, +}) +``` + +::: diff --git a/docs/config/input.md b/docs/config/input.md new file mode 100644 index 000000000..697539a74 --- /dev/null +++ b/docs/config/input.md @@ -0,0 +1,60 @@ +--- +layout: doc + +title: Config +outline: deep +--- + +# input + +You can use `input.path` or `input.data` depending on the needs you have. + +### input.path + +Define your Swagger/OpenAPI file. This can be an absolute path or a path relative to the `root`. + +- **Type:** `string`
+- **Required:** `true` + +::: code-group + +```typescript [kubb.config.ts] +import { defineConfig } from '@kubb/core' + +export default defineConfig({ + input: { + path: './petStore.yaml', + }, + output: { + path: './src/gen', + }, +}) +``` + +::: + +### input.data + +`string` or `object` containing your Swagger/OpenAPI + +- **Type:** `string | unknown`
+- **Required:** `true` + +::: code-group + +```typescript [kubb.config.ts] +import { defineConfig } from '@kubb/core' + +import petStore from './petStore.yaml' + +export default defineConfig({ + input: { + data: petStore, + }, + output: { + path: './src/gen', + }, +}) +``` + +::: diff --git a/docs/config/name.md b/docs/config/name.md new file mode 100644 index 000000000..102a08682 --- /dev/null +++ b/docs/config/name.md @@ -0,0 +1,57 @@ +--- +layout: doc + +title: Config +outline: deep +--- + +# name + +Optional config name to show in CLI output. + +- **Type:** `string`
+- **Default:** `process.cwd()`
+ +::: code-group + +```typescript [kubb.config.ts] +import { defineConfig } from '@kubb/core' + +export default defineConfig({ + name: 'petStore', + root: '.', + input: { + path: './petStore.yaml', + }, + output: { + path: './src/gen', + }, +}) +``` + +```typescript [kubb.config.ts] +import { defineConfig } from '@kubb/core' + +export default defineConfig([ + { + name: 'petStore', + root: '.', + input: { + path: './petStore.yaml', + }, + output: { + path: './src/gen', + }, + }, + { + name: 'petStoreV2', + root: '.', + input: { + path: './petStoreV2.yaml', + }, + output: { + path: './src/gen-v2', + }, + }, +]) +``` diff --git a/docs/config/output.md b/docs/config/output.md new file mode 100644 index 000000000..940b66271 --- /dev/null +++ b/docs/config/output.md @@ -0,0 +1,83 @@ +--- +layout: doc + +title: Config +outline: deep +--- + +# output + +### output.path + +Path to be used to export all generated files.
+This can be an absolute path, or a path relative from the defined `root` option. + +- **Type:** `string`
+- **Required:** `true` + +::: code-group + +```typescript [kubb.config.ts] +import { defineConfig } from '@kubb/core' + +export default defineConfig({ + input: { + path: './petStore.yaml', + }, + output: { + path: './src/gen', + }, +}) +``` + +::: + +### output.clean + +Clean output directory before each build. + +- **Type:** `boolean`
+ +::: code-group + +```typescript [kubb.config.ts] +import { defineConfig } from '@kubb/core' + +export default defineConfig({ + input: { + path: './petStore.yaml', + }, + output: { + path: './src/gen', + clean: true, + }, +}) +``` + +::: + +### output.write + +Write files to the fileSystem. + +- **Type:** `boolean`
+- **Default:** `true` + +::: code-group + +```typescript [kubb.config.ts] +import { defineConfig } from '@kubb/core' + +export default defineConfig({ + input: { + path: './petStore.yaml', + }, + output: { + path: './src/gen', + clean: true, + write: true, + }, +}) +``` + +::: diff --git a/docs/config/overview.md b/docs/config/overview.md new file mode 100644 index 000000000..90cf5663d --- /dev/null +++ b/docs/config/overview.md @@ -0,0 +1,57 @@ +--- +layout: doc + +title: Config +outline: deep +--- + +# Options + +This page is a reference to the different options you can use for configuring your Kubb config. +By setting the following options you can override the default behaviour of Kubb and even extend it with your own plugins. + +::: info Options + +[name](/config/name) +
+[root](/config/root) +
+[input.path](/config/input#input-path) +
+[input.data](/config/input#input-data) +
+[output.path](/config/output#output-path) +
+[output.clean](/config/output#output-clean) +
+[output.write](/config/output#output-write) +
+[plugins](/config/plugins) +
+[hooks.done](/config/hooks#hooks-done) + +::: + +::: code-group + +```typescript [kubb.config.ts] +import { defineConfig } from '@kubb/core' +import createSwagger from '@kubb/swagger' + +export default defineConfig({ + input: { + path: './petStore.yaml', + }, + output: { + path: './src/gen', + }, + plugins: [ + createSwagger({ + output: 'schemas', + validate: true, + }), + ], +}) +``` + +::: diff --git a/docs/config/plugins.md b/docs/config/plugins.md new file mode 100644 index 000000000..c3fc3a756 --- /dev/null +++ b/docs/config/plugins.md @@ -0,0 +1,39 @@ +--- +layout: doc + +title: Config +outline: deep +--- + +# plugins + +- **Type:** `Array`
+ +Array of Kubb plugins to use. The plugin/package can have some extra options defined by the plugin. +Sometimes a plugin is depended on another plugin, if that's the case you will get an error back from the plugin you installed.([see pre](/reference/pluginManager)).

+ +How to use and setup plugins, see [plugins](/plugins/overview). + +::: code-group + +```typescript [kubb.config.ts] +import { defineConfig } from '@kubb/core' +import createSwagger from '@kubb/swagger' + +export default defineConfig({ + input: { + path: './petStore.yaml', + }, + output: { + path: './src/gen', + }, + plugins: [ + createSwagger({ + output: 'schemas', + validate: true, + }), + ], +}) +``` + +::: diff --git a/docs/config/root.md b/docs/config/root.md new file mode 100644 index 000000000..7a04981ae --- /dev/null +++ b/docs/config/root.md @@ -0,0 +1,31 @@ +--- +layout: doc + +title: Config +outline: deep +--- + +# root + +Project root directory. Can be an absolute path, or a path relative from the location of the config file itself. + +- **Type:** `string`
+- **Default:** `process.cwd()`
+ +::: code-group + +```typescript [kubb.config.js] +import { defineConfig } from '@kubb/core' + +export default defineConfig({ + root: '.', + input: { + path: './petStore.yaml', + }, + output: { + path: './src/gen', + }, +}) +``` + +::: diff --git a/docs/examples/advanced.md b/docs/examples/advanced.md index e908be255..35f67f284 100644 --- a/docs/examples/advanced.md +++ b/docs/examples/advanced.md @@ -4,7 +4,7 @@ aside: false --- -## Motivation - -Swagger/OpenAPI has been used a lot as a contract between frontend and backend teams, this was the same for the last couple of projects I did. Every project is different so it always came down in choosing one of the provided code generators or the default one of Swagger. But that wasn't enough for my needs ๐Ÿ™. - -Main features โœจ: - -- Every generated client(React-Query, MSW, Zod, ...) is contained in it's own package. -- Clean code that follows the examples of the client(no extra un-needed boilerplate code). -- Out-of-box TypeScript (with JSDoc) support. -- Open-source first. -- Plugins system based on Rollup, esbuild, -- CLI support. - -## Installation - -You can install Kubb via [NPM](https://www.npmjs.com/). - -::: code-group - -```shell [bun ] -bun add @kubb/cli @kubb/core -``` - -```shell [pnpm ] -pnpm add @kubb/cli @kubb/core -``` - -```shell [npm ] -npm install @kubb/cli @kubb/core -``` - -```shell [yarn ] -yarn add @kubb/cli @kubb/core -``` - -::: - -See [Installation](/guide/installation) +## ๐Ÿ”ฅ Features -## Configuration File +Kubb has the following features: -Kubb uses [Cosmiconfig](https://github.com/davidtheclark/cosmiconfig) for the configuration file support. -This means you can configure Kubb via (in order of precedence): +- **Easy to Configure**: One of the goals of Kubb is to provide out-of-the-box plugins and utils for converting your Swagger/OpenAPI file to generated code.

You want to use a Swagger/OpenAPI file or URL, you want to split up the generated code based on a tag in the file, you want to use multiple Swagger/OpenApi files, we have you covered! +- **Generate SDK's**: Convert your Swagger/OpenAPI file to TypeScript, React-Query, Zod, Zodios, Faker.js, MSW and Axios. +- **Templates**: Override/change the generated output of a plugin with the help of [JSX templates(React)](/reference/templates). +- **Plugin Ecosystem**: Kubb has a [plugin system](/plugins/introdution) that makes it possible to change or add functionalities based on your needs. +- **CLI**: See in real-time what is getting generated or processed. +- And so much more ... -- A "kubb" key in your package.json file. -- A `.kubbrc` file written in JSON or YAML. -- A `.kubbrc.json` file. -- A `.kubbrc.js`, `.kubbrc.cjs`, `kubb.config.js`, or `kubb.config.cjs` file that exports an object using module.exports. -- A `.kubbrc.ts` or `kubb.config.ts` file that exports an object using export default. +## ๐Ÿง‘โ€๐Ÿ’ป Community -::: tip -You can also use `configs/kubb.config.ts` or `.config/kubb.config.ts` instead of `kubb.config.ts` in the root of your project. -::: +Come and chat with us on [Discord](https://discord.gg/shfBFeczrm)! We're always looking for some contributions. -See [kubb.config.js](/guide/options) on how to configure Kubb. +See [kubb.config.js](/guide/configure) on how to configure Kubb. diff --git a/docs/guide/options.md b/docs/guide/options.md deleted file mode 100644 index 779f8d2ba..000000000 --- a/docs/guide/options.md +++ /dev/null @@ -1,346 +0,0 @@ ---- -layout: doc - -title: Options -outline: deep ---- - -# Options - -This page is a reference to the different options you can use for configuring your Kubb config. -By setting the following options you can override the default behaviour of Kubb and even extend it with your own plugins. - -## name - -Optional config name to show in CLI output. - -::: info -Type: `string`
-Default: `process.cwd()`
- -::: code-group - -```typescript [kubb.config.js] -import { defineConfig } from '@kubb/core' - -export default defineConfig({ - name: 'petStore', - root: '.', - input: { - path: './petStore.yaml', - }, - output: { - path: './src/gen', - }, -}) -``` - -```typescript [kubb.config.js] -import { defineConfig } from '@kubb/core' - -export default defineConfig([ - { - name: 'petStore', - root: '.', - input: { - path: './petStore.yaml', - }, - output: { - path: './src/gen', - }, - }, - { - name: 'petStoreV2', - root: '.', - input: { - path: './petStoreV2.yaml', - }, - output: { - path: './src/gen-v2', - }, - }, -]) -``` - -::: - -## root - -Project root directory. Can be an absolute path, or a path relative from the location of the config file itself. - -::: info -Type: `string`
-Default: `process.cwd()`
- -::: code-group - -```typescript [kubb.config.js] -import { defineConfig } from '@kubb/core' - -export default defineConfig({ - root: '.', - input: { - path: './petStore.yaml', - }, - output: { - path: './src/gen', - }, -}) -``` - -::: - -## input - -You can use `input.path` or `input.data` depending on the needs you have. - -### path - -Define your Swagger/OpenAPI file.
-This can be an absolute path or a path relative to the `root`. - -::: info -Type: `string`
-Required: `true` - -::: code-group - -```typescript [kubb.config.js] -import { defineConfig } from '@kubb/core' - -export default defineConfig({ - input: { - path: './petStore.yaml', - }, - output: { - path: './src/gen', - }, -}) -``` - -::: - -### data - -`string` or `object` containing your Swagger/OpenAPI - -::: info -Type: `string | unknown`
-Required: `true` - -::: code-group - -```typescript [kubb.config.js] -import { defineConfig } from '@kubb/core' - -import petStore from './petStore.yaml' - -export default defineConfig({ - input: { - data: petStore, - }, - output: { - path: './src/gen', - }, -}) -``` - -::: - -## output - -### path - -Path to be used to export all generated files.
-This can be an absolute path, or a path relative from the defined `root` option. - -::: info -Type: `string`
-Required: `true` - -::: code-group - -```typescript [kubb.config.js] -import { defineConfig } from '@kubb/core' - -export default defineConfig({ - input: { - path: './petStore.yaml', - }, - output: { - path: './src/gen', - }, -}) -``` - -::: - -### clean - -Clean output directory before each build. - -::: info -Type: `boolean`
- -::: code-group - -```typescript [kubb.config.js] -import { defineConfig } from '@kubb/core' - -export default defineConfig({ - input: { - path: './petStore.yaml', - }, - output: { - path: './src/gen', - clean: true, - }, -}) -``` - -::: - -### write - -Write files to the fileSystem. - -::: info -Type: `boolean`
-Default: `true` - -::: code-group - -```typescript [kubb.config.js] -import { defineConfig } from '@kubb/core' - -export default defineConfig({ - input: { - path: './petStore.yaml', - }, - output: { - path: './src/gen', - clean: true, - write: true, - }, -}) -``` - -::: - -## plugins[] - -```typescript -import type { KubbUserPlugin } from '@kubb/core' - -type Plugins = Array -``` - -Array of Kubb plugins to use. The plugin/package can have some extra options defined by the plugin. -Sometimes a plugin is depended on another plugin, if that's the case you will get an error back from the plugin you installed.([see validate](/reference/pluginManager#1-validate)) - -([see configure](/guide/configure)) - -When using JSON, the structure will be a little bit different. -Here we are using the same syntax like how [Babel](https://babeljs.io/docs/en/plugins/) makes it possible to use plugins with extra options. - -``` -[pluginName: string, options: PluginOptions] -``` - -::: info -::: code-group - -```json [kubb.json] -{ - "$schema": "@kubb/core/schemas/config.json", - "root": ".", - "input": { - "path": "./petStore.yaml" - }, - "output": { - "path": "./src/gen" - }, - "plugins": [ - [ - "@kubb/swagger", - { - "output": "schemas", - "validate": true - } - ] - ] -} -``` - -```typescript [kubb.config.js] -import { defineConfig } from '@kubb/core' -import createSwagger from '@kubb/swagger' - -export default defineConfig({ - input: { - path: './petStore.yaml', - }, - output: { - path: './src/gen', - }, - plugins: [ - [ - '@kubb/swagger', - { - output: 'schemas', - validate: true, - }, - ], - ], -}) -``` - -::: - -## hooks[] - -Hooks that will be called when a specific action is triggered in Kubb. - -### done - -Hook that will be triggered at the end of Kubb's generation.
-Useful for running Prettier or ESLint to format/lint your code. - -::: info -Type: `string | string[]`
- -::: code-group - -```typescript [kubb.config.js] -import { defineConfig } from '@kubb/core' - -export default defineConfig({ - hooks: { - done: ['npx prettier --write .'], - }, - input: { - path: './petStore.yaml', - }, - output: { - path: './src/gen', - }, -}) -``` - -```typescript [kubb.config.js] -import { defineConfig } from '@kubb/core' - -export default defineConfig({ - hooks: { - done: 'npx prettier --write .', - }, - input: { - path: './petStore.yaml', - }, - output: { - path: './src/gen', - }, -}) -``` - -::: diff --git a/docs/guide/quick-start.md b/docs/guide/quick-start.md index 50e807bd8..0262e83d2 100644 --- a/docs/guide/quick-start.md +++ b/docs/guide/quick-start.md @@ -10,7 +10,13 @@ outline: deep ## Intro The easiest way to get started with Kubb is just run the following in your cli. -Kubb will search based on the [configuration order](/guide/introduction.html#configuration-file) which file/config it needs to use. +Kubb will search based on the [configuration order](/guide/configure#usage) which file/config it needs to use. + +::: tip +When using a `import` statement you need to set `"type": "module"` in your `package.json`. + +You can also rename your file to `kubb.config.mjs` to use ESM or `kubb.config.cjs for CJS. +::: ```bash kubb @@ -45,7 +51,9 @@ export default defineConfig(async () => { ## Advanced example +::: tip Since version `2.x.x` we also support using multiple entry(OpenAPI/Swagger) files. +::: ```bash kubb --config kubb.config.js @@ -95,75 +103,4 @@ export default defineConfig(async () => { ::: -## Examples with plugins - -```bash -kubb --config kubb.config.js -``` - -::: code-group - -```typescript [kubb.config.js] -import { defineConfig } from '@kubb/core' -import createSwagger from '@kubb/swagger' -import createSwaggerTanstackQuery from '@kubb/swagger-tanstack-query' -import createSwaggerTS from '@kubb/swagger-ts' - -export default defineConfig(async () => { - return { - root: '.', - input: { - path: './petStore.yaml', - }, - output: { - path: './src/gen', - }, - plugins: [ - createSwagger({}), - createSwaggerTS({}), - createSwaggerTanstackQuery({}), - ], - } -}) -``` - -::: - -## Example with plugins in JSON format - -```bash -kubb --config kubb.config.js -``` - -::: code-group - -```typescript [kubb.config.js] -import { defineConfig } from '@kubb/core' - -export default defineConfig(() => { - return { - root: '.', - input: { - path: './petStore.yaml', - }, - output: { - path: './src/gen', - }, - plugins: [ - ['@kubb/swagger', { - output: false, - }], - ['@kubb/swagger-ts', { - output: 'models/ts', - }], - ['@kubb/swagger-tanstack-query', { - output: './reactQuery', - }], - ], - } -}) -``` - -::: - -If you're looking for a fully functioning example, please have a look at our [simple codesandbox example](https://codesandbox.io/s/github/kubb-project/kubb/tree/alpha/examples/typescript). +If you're looking for a fully functioning example, please have a look at our [simple CodesSandbox example](https://codesandbox.io/s/github/kubb-project/kubb/tree/beta/examples/typescript). diff --git a/docs/index.md b/docs/index.md index 0e5e9f063..55b390172 100644 --- a/docs/index.md +++ b/docs/index.md @@ -73,5 +73,11 @@ features: dark: ./feature/plugins-dark.svg light: ./feature/plugins-light.svg title: Extensible with plugins - details: Create your own plugin or fork and change one of the default plugins with your own flavour without the need of forking the full project.
Learn more
+ details: Create your own plugin or fork and change one of the default plugins with your own flavour without the need of forking the full project.
Learn more
+ - icon: + src: ./feature/react.svg + height: 24 + title: Templates + details: Customize the generated files/output based on a custom defined JSX(React) template.
Learn more
+ --- diff --git a/docs/plugins/development/core.md b/docs/plugins/development/core.md new file mode 100644 index 000000000..0c68f506b --- /dev/null +++ b/docs/plugins/development/core.md @@ -0,0 +1,8 @@ +--- +layout: doc + +title: Development +outline: deep +--- + +# Plugin core diff --git a/docs/plugins/development/system.md b/docs/plugins/development/system.md new file mode 100644 index 000000000..86b06aa18 --- /dev/null +++ b/docs/plugins/development/system.md @@ -0,0 +1,8 @@ +--- +layout: doc + +title: Development +outline: deep +--- + +# Plugin system diff --git a/docs/plugins/introduction.md b/docs/plugins/development/template.md similarity index 56% rename from docs/plugins/introduction.md rename to docs/plugins/development/template.md index 70c3e4e57..cb0ea6f75 100644 --- a/docs/plugins/introduction.md +++ b/docs/plugins/development/template.md @@ -1,21 +1,11 @@ --- layout: doc -title: Plugins +title: Development outline: deep --- -# Plugins - -Plugins are a great way to extend Kubb's basic functionality. Even the package `@kubb/core` is a plugin, which also contains the building blocks in creating your own plugin. We have already written some plugins so you can easily get started with TypeScript or ReactQuery. - -::: tip -Do you have an idea or a specific change is needed, feel free to create an issue. -::: - -
- -## Template +# Plugin template The easiest way to get started with creating your own Kubb plugin is to use our [template on GitHub](https://github.com/kubb-project/plugin-template) or clone the following repo [https://github.com/kubb-project/plugin-template](https://github.com/kubb-project/plugin-template). @@ -28,28 +18,28 @@ $ git clone https://github.com/kubb-project/plugin-template.git ```typescript import pathParser from 'node:path' -import { createPlugin, getPathMode, validatePlugins, writeIndexes, KubbPlugin } from '@kubb/core' +import { FileManager, createPlugin } from '@kubb/core' import { pluginName as swaggerPluginName } from '@kubb/swagger' import { camelCase, camelCaseTransformMerge } from 'change-case' -import type { File } from '@kubb/core' -import type { PluginOptions as SwaggerPluginOptions } from '@kubb/swagger' +import type { KubbFile } from '@kubb/core' import type { PluginOptions } from './types.ts' +import path from 'node:path' export const pluginName = 'plugin-demo' satisfies PluginOptions['name'] -export const pluginKey = [pluginName] satisfies PluginOptions['key'] +export const pluginKey: PluginOptions['key'] = [pluginName] satisfies PluginOptions['key'] export const definePlugin = createPlugin((options) => { const { output = 'demo' } = options - let pluginsOptions: [KubbPlugin] return { name: pluginName, options, + pre: [swaggerPluginName], resolvePath(fileName, directory, options) { const root = pathParser.resolve(this.config.root, this.config.output.path) - const mode = getPathMode(pathParser.resolve(root, output)) + const mode = FileManager.getMode(path.resolve(root, output)) if (mode === 'file') { /** @@ -65,22 +55,21 @@ export const definePlugin = createPlugin((options) => { return camelCase(name, { delimiter: '', stripRegexp: /[^A-Z0-9$]/gi, transform: camelCaseTransformMerge }) }, async buildStart() { - // const [swaggerPlugin] = pluginsOptions // const oas = await swaggerApi.getOas() - const files: File[] = [ + const files: KubbFile.File[] = [ { - fileName: 'test.ts', + baseName: 'test.ts', path: this.resolvePath({ - fileName: 'test.ts', - pluginName, + baseName: 'test.ts', + pluginKey: this.plugin.key, })!, source: "export const hello = 'world';", }, ] await this.addFile(...files) - console.log('Build start') + console.log('Build started') }, async buildEnd() { if (this.config.output.write === false) { @@ -88,20 +77,17 @@ export const definePlugin = createPlugin((options) => { } const root = pathParser.resolve(this.config.root, this.config.output.path) - const files = await writeIndexes(root, { extensions: /\.ts/, exclude: [/schemas/, /json/] }) - if (files) { - await this.addFile(...files) - } - - console.log('Build end') + await this.fileManager.addIndexes({ + root, + extName: '.ts', + meta: { pluginKey: this.plugin.key }, + options: { + output, + }, + }) + console.log('Build ended') }, } }) ``` - -Our plugin system is based on some ideas of the following packages: - -- [Rollup's](https://github.com/rollup/rollup/blob/master/docs/05-plugin-development.md) -- [Unplugin](https://github.com/unjs/unplugin) -- [Snowpack](https://www.snowpack.dev/guides/plugins) diff --git a/docs/plugins/overview.md b/docs/plugins/overview.md new file mode 100644 index 000000000..bd0f9f174 --- /dev/null +++ b/docs/plugins/overview.md @@ -0,0 +1,22 @@ +--- +layout: doc + +title: Plugins +outline: deep +--- + +# Plugins + +Plugins are a great way to extend Kubb's basic functionality. Even the package `@kubb/core` is a plugin, which also contains the building blocks in creating your own plugin. We have already written some plugins so you can easily get started with TypeScript or ReactQuery. + +::: tip +Do you have an idea or a specific change is needed, feel free to create an issue. +::: + +
+ +Our plugin system is based on some ideas of the following packages: + +- [Rollup's](https://github.com/rollup/rollup/blob/master/docs/05-plugin-development.md) +- [Unplugin](https://github.com/unjs/unplugin) +- [Snowpack](https://www.snowpack.dev/guides/plugins) diff --git a/docs/plugins/react/components/text.md b/docs/plugins/react/components/text.md index 409d67cc1..7c0273288 100644 --- a/docs/plugins/react/components/text.md +++ b/docs/plugins/react/components/text.md @@ -7,6 +7,8 @@ outline: deep # Text +## Text + ::: code-group ```tsx [simple] @@ -37,7 +39,7 @@ export const test = 2 ::: -# Text with indent +## Text with indent ::: code-group diff --git a/docs/public/feature/react.svg b/docs/public/feature/react.svg new file mode 100644 index 000000000..cecc853ff --- /dev/null +++ b/docs/public/feature/react.svg @@ -0,0 +1 @@ + diff --git a/docs/readme.md b/docs/readme.md index 0bb3818dd..71dabc59d 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -11,7 +11,7 @@

- View Demo + View Demo ยท Documentation ยท diff --git a/docs/reference/overview.md b/docs/reference/overview.md new file mode 100644 index 000000000..5ec8f3d4c --- /dev/null +++ b/docs/reference/overview.md @@ -0,0 +1,8 @@ +--- +layout: doc + +title: Reference +outline: deep +--- + +# Reference diff --git a/packages/cli/src/utils/getCosmiConfig.ts b/packages/cli/src/utils/getCosmiConfig.ts index 2004531ff..95e15ea32 100644 --- a/packages/cli/src/utils/getCosmiConfig.ts +++ b/packages/cli/src/utils/getCosmiConfig.ts @@ -48,13 +48,13 @@ export async function getCosmiConfig(moduleName: string, config?: string): Promi `.${moduleName}rc.ts`, `.${moduleName}rc.js`, - `.${moduleName}rc.cjs`, `.${moduleName}rc.mjs`, + `.${moduleName}rc.cjs`, `${moduleName}.config.ts`, `${moduleName}.config.js`, - `${moduleName}.config.cjs`, `${moduleName}.config.mjs`, + `${moduleName}.config.cjs`, ] const explorer = cosmiconfig(moduleName, { cache: false,