From 9707a579ca38f787953754809defc24c667b87a5 Mon Sep 17 00:00:00 2001 From: Stijn Van Hulle Date: Sun, 6 Oct 2024 21:07:01 +0200 Subject: [PATCH] chore: cleanup --- docs/.vitepress/config.ts | 8 - docs/blog/benefits-of-templates.md | 114 ------------- docs/blog/v2.md | 224 ------------------------- docs/knowledge-base/migration-guide.md | 4 +- 4 files changed, 2 insertions(+), 348 deletions(-) delete mode 100644 docs/blog/benefits-of-templates.md delete mode 100644 docs/blog/v2.md diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 580932974..c0b63204d 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -312,14 +312,6 @@ const blogSidebar = [ text: 'Release of Kubb 3.0', link: '/blog/v3', }, - { - text: 'Release of Kubb 2.0', - link: '/blog/v2', - }, - { - text: 'Benefits of using JSX for templates', - link: '/blog/benefits-of-templates', - }, ] const tutorialsSidebar = [ diff --git a/docs/blog/benefits-of-templates.md b/docs/blog/benefits-of-templates.md deleted file mode 100644 index c8b563623..000000000 --- a/docs/blog/benefits-of-templates.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -layout: doc - -title: Benefits of using JSX for templates -outline: deep ---- - -Published: 2023-12-08 - -# Benefits of using JSX for templates - -Since v2, `Kubb` has been starting to use JSX templates to create its generated code. Previously, we used template strings which became harder to maintain due to increasing complexity. - -This made us wonder if it was possible to use React and JSX to create our templates. - -## Concepts - -### What is a template engine? - -A template engine is a software program designed to combine templates with a data model to produce a document or output. The language used to write these templates is called a template language. The resulting document can be a web page, a document, or even source code. One specific use case for template engines is source code generation. - -Some well known template engines are [Mustache](https://mustache.github.io/), [Handlebars](https://handlebarsjs.com/), and [EJS](https://ejs.co/). To create JavaScript/ you can also use the [TypesScript compiler API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API) to create JavaScript/TypeScript and the OpenAPI TypeScript generator uses [Handlebars](https://handlebarsjs.com/). - -### What is source code generation? - -Source code generation is a technique used in programming where code is automatically generated based on a set of pre-defined rules or templates. This technique can save developers time and effort by automating repetitive tasks and reducing the likelihood of errors. Code generation can be used for a variety of purposes, including creating boilerplate code, generating code from models, and producing code for specific platforms or frameworks. Many commonly used tools, such as graphql, OpenAPI, and gRPC, use code generation under the hood. - -## The search for kubb's search engine - -### TypeScript compiler - -We've looked into [TypesScript compiler API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API), but it has a steep learning curve and it does not fit our needs.
- -### Ink - -Our search brought us to the project named [Ink](https://github.com/vadimdemedes/ink) which is a CLI tool that uses React/JSX as its template engine. The project's bio says the following: - -> React for CLIs. Build and test your CLI output using components. - -```typescript -import React, { useState, useEffect } from 'react' -import { render, Text } from 'ink' - -const Counter = () => { - const [counter, setCounter] = useState(0) - - useEffect(() => { - const timer = setInterval(() => { - setCounter(previousCounter => previousCounter + 1) - }, 100) - - return () => { - clearInterval(timer) - } - }, []) - - return {counter} tests passed -} - -render() -``` - - -
-After some digging around in their code we came up with a solution that would benefit Kubb. - -We can use JSX as the template engine and provide some hooks that could be used to access some `Kubb` specific behavior.
- -The hooks will allow the engine to use the `PluginManager` instance or access the `FileManager` for example. When using the `@kubb/swagger` plugin, we could also provide hooks that would return the current operation/path/oas instance.
-We saw a lot of opportunities in this approach, so we started with a small POC for one of our plugins. As of today(december 2023), we are using JSX templates in all our plugins. - -## Examples - -### @kubb/plugin - -Below you can find an example of our previous templates. The code is not easy to read. An improvement could be to split the code up, but this will have to be paired with prop drilling, which is something we wish to avoid.
- -```typescript -const code = ` -export function ${name} <${generics.join(', ')}>(${params}): Promise { - return client<${clientGenerics.join(', ')}>({ - method: "${method}", - url: ${url}, - ${schemas.queryParams?.name ? 'params,' : ''} - ${schemas.request?.name ? 'data,' : ''} - ${schemas.headerParams?.name ? 'headers: { ...headers, ...options.headers },' : ''} - ...options - }); -}; -` -``` - -With the React/JSX example, we could use `context` and define some options in the root. -If you compare the previous template with an example using JSX/React, you can already see it's easier to read. Adding if structures will also be easier with the JSX syntax: - -`{ shouldBeTrue === true ? : undefined }`. - -```typescript - - {` - return client<${clientGenerics.join(', ')}>({ - method: "${method}", - url: ${url}, - ${schemas.queryParams?.name ? 'params,' : ''} - ${schemas.request?.name ? 'data,' : ''} - ${schemas.headerParams?.name ? 'headers: { ...headers, ...options.headers },' : ''} - ...options - })`} - -``` - -## Overriding with templates - -We've made a guide on how you can override templates in our plugins: [templates the guide](/tutorials/templates). diff --git a/docs/blog/v2.md b/docs/blog/v2.md deleted file mode 100644 index fa40da7f5..000000000 --- a/docs/blog/v2.md +++ /dev/null @@ -1,224 +0,0 @@ ---- -layout: doc - -title: 🎉 Release of Kubb 2.0 🎉 -outline: deep ---- - - - -Published: 2023-12-08 - -# 🎉 Release of Kubb 2.0 🎉 - -## Introduction - -Kubb has been available for almost a year and we have learned a lot since v1. Most of the changes that has been done are related to the internal structure(how we handle files, plugins, ...). This means your project can generate faster code in v2 than it was the case in v1. - -Another big change is that it will now also be possible to use multiple of the same plugins and with the introduction of `exclude/include/override` you can generate code for just one specific path. - -The introduction of `React` and `JSX` was also a big change, in the background we can now 'translate' Swagger/OpenAPI files to generated code(TypeScript, ReactQuery, ...). More about why and how we did this can be found in the [Benefits of using JSX for templates](/blog/benefits-of-templates) blog. - -Because of this change we can now use [templates](/reference/templates) to override the default behaviour of for example the `useQuery` of @tanstack/query. - -## Breaking Changes - -In practice, most of the "breaking" changes should not have an actual effect, and we expect that many projects can just update with very few changes. - -- `skipBy` has been replaced by `exclude` -- `overrideBy` has been replaced by `override` -- `groupBy` has been replaced by `group` -- `client` has been removed in favour of using `client.importPath`(added in a previous version) -- `output` has been replaced by `output.path` when using a plugin -- `exportAs` has been replaced by `output.exportAs` when using a plugin (`@kubb/plugin-ts` only) - -## New Features - -### Templates - -With templates you can override the default behaviour of our plugins. - -- [Benefits of using JSX for templates](/blog/benefits-of-templates) -- [Guide in create your own template](/tutorials/templates) - -### Exclude and include - -All plugins now have an `exclude` and `include` option, with those you can specify which `path`, `operation`, `method` or `tag` you want to include/exclude in the generation. - -```typescript [kubb.config.ts] -import { defineConfig } from '@kubb/core' - -export default defineConfig(() => { - return { - root: '.', - input: { - path: './petStore.yaml', - }, - output: { - path: './src/gen', - clean: true, - }, - plugins: [ - ['@kubb/plugin-oas', { - output: { - path: 'schemas', - }, - validate: true, - }], - [ - '@kubb/plugin-client', - { - output: { - path: './clients/axios', - }, - exclude: [ - { - type: 'tag', - pattern: 'store', - }, - ], - }, - ], - ], - } -}) -``` - -### Use multiple of the same plugin - -In v2 it will now be possible to use multiple of the same plugin(with other options).
-The following example will add the types that have a `tag` 'store' set to the `types/store` folder and the ones with `tag` 'pet' to `types/pet`. [Setup with multiple of the same plugin](/guide/configure#multiple).
- -```typescript [kubb.config.ts] -import { defineConfig } from '@kubb/core' -import { pluginOas } from '@kubb/plugin-oas' -import { pluginTs } from '@kubb/plugin-ts' - -export default defineConfig(() => { - return { - root: '.', - input: { - path: './petStore.yaml', - }, - output: { - path: './src/gen', - }, - plugins: [ - pluginOas( - { - 'output': 'schemas', - 'validate': true, - }, - ), - pluginTs({ - 'output': { - path: 'types/store', - }, - include: [ - { - type: 'tag', - pattern: 'store', - }, - ], - }), - pluginTs({ - 'output': { - path: 'types/pet', - }, - include: [ - { - type: 'tag', - pattern: 'pet', - }, - ], - dateType: 'date', - }), - ], - } -}) -``` - -### Multiple configs in one config file - -Next to having multiple plugins, it will also be possible to use multiple configs in one `kubb.config.ts` file. - -```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', - }, - }, -]) -``` - -## Internal changes - -::: info -[GitHub issue](https://github.com/kubb-labs/kubb/issues/556) -::: - -- Faster execution time because of a change in our FilesManager with an updated queue system. -- [Add a name](/config/name) to the CLI as a prefix(when using multiple configs in one config file). -- Improved logging. -- Use of pluginKey instead of pluginName(so multiple of the same plugin can be supported). -- Move of our generic types to `@kubb/types`. -- Use of [templates](/reference/templates) for all internal packages with the use of `@kubb/react`. -- Improved test coverage. -- Use of TypeScript v5.3.0. -- Support for MSW v2. -- Support for @tanstack/query v5(added `useSuspenseQuery`). -- [Infer](/plugins/plugin-ts/infer) with `@kubb/plugin-ts/oas`(experimental). -- [Disable the creation of barrel/index](/plugins/plugin-ts/#output-exporttype) files and [change extension](/plugins/plugin-ts/#output-extname). - -## Thanks - -A big thanks to everyone using Kubb and also the ones that have already contributed to Kubb! - -::: warning Twitter/X -We now also have a Twitter/X account: [x.com/kubbproject](https://twitter.com/kubbproject). - -::: - - - - - - Star History Chart - - - -👋🏽 [Stijn Van Hulle](https://twitter.com/stijnvanhulle) diff --git a/docs/knowledge-base/migration-guide.md b/docs/knowledge-base/migration-guide.md index dba4f0579..dc3990f80 100644 --- a/docs/knowledge-base/migration-guide.md +++ b/docs/knowledge-base/migration-guide.md @@ -1,11 +1,11 @@ --- layout: doc -title: Migration to Kubb v3 +title: Migrating to Kubb v3 outline: deep --- -# Migration to Kubb v3 +# Migrating to Kubb v3 ## New Features