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.

Because of this change we can now use 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/swagger-ts only)

New Features

Templates

With templates you can override the default behaviour of our plugins.

• What are templates
• Benefits of using JSX for templates
• Guide in create your own template

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.

import { defineConfig } from '@kubb/core'

export default defineConfig(() => {
  return {
    root: '.',
    input: {
      path: './petStore.yaml',
    },
    output: {
      path: './src/gen',
      clean: true,
    },
    plugins: [
      ['@kubb/swagger', {
        output: {
          path: 'schemas',
        },
        validate: true,
      }],
      [
        '@kubb/swagger-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.

import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/swagger-oas'
import { pluginTs } from '@kubb/swagger-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.

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

• Faster execution time because of a change in our FilesManager with an updated queue system.
• Add a 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 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 with @kubb/swagger-ts/oas(experimental).
• Disable the creation of barrel/index files and change extension.

Thanks

A big thanks to everyone using Kubb and also the ones that have already contributed to Kubb!

Twitter/X

We now also have a Twitter/X account: x.com/kubbproject.

👋🏽 Stijn Van Hulle