@kubb/plugin-swr 5.2.2 → 5.2.4

package/docs/guides/calling-operations.md

@@ -0,0 +1,81 @@
+# Call operations
+
+`@kubb/plugin-swr` generates a typed SWR hook for each operation. `GET` operations get `useSWR` hooks such as `useGetPetById`, and `POST`, `PUT`, `PATCH`, and `DELETE` operations get `useSWRMutation` hooks such as `useCreatePet`. Each hook calls the client function from `@kubb/plugin-fetch` or `@kubb/plugin-axios`.
+
+## Queries
+
+A query hook takes the operation's grouped request config (`path`, `query`, `headers`, whichever the operation declares) as its first argument:
+
+```typescript
+import { useGetPetById } from './gen/hooks/useGetPetById'
+
+const { data, error, isLoading } = useGetPetById({ path: { petId: 1n } })
+```
+
+The second argument takes `query` (any `SWRConfiguration`), `client` (request config for this call, such as `baseURL`), and the Kubb options `shouldFetch` and `immutable`, covered in [Skip requests until ready](#skip-requests-until-ready) and [Fetch immutable data](#fetch-immutable-data):
+
+```typescript
+import { useGetPetById } from './gen/hooks/useGetPetById'
+
+useGetPetById(
+  { path: { petId: 1n } },
+  {
+    query: { refreshInterval: 30_000 },
+    client: { baseURL: 'https://api.example.com/v1' },
+  },
+)
+```
+
+The exported `queryKey` helper includes the operation URL and request parameters. Pass it to SWR's `mutate` to update or revalidate that entry.
+
+## Mutations
+
+A mutation hook takes only an options object. Pass the grouped request config to `trigger(...)`:
+
+```typescript
+import { mutate } from 'swr'
+import { useCreatePet } from './gen/hooks/useCreatePet'
+import { getPetsQueryKey } from './gen/hooks/useGetPets'
+
+const { trigger, isMutating } = useCreatePet({
+  mutation: { onSuccess: () => mutate(getPetsQueryKey()) },
+})
+
+await trigger({ body: { name: 'Fluffy' } })
+```
+
+A `mutationKey` helper is exported next to the hook.
+
+## Errors and transport
+
+Each generated hook calls the client function with `throwOnError: true`. A failed request sets SWR's `error`, typed from the error responses in the spec. Set the base URL, authentication, interceptors, serialization, and validation on the client plugin. See the [plugin-fetch](https://kubb.dev/extensions/kubb-labs/plugin-fetch) or [plugin-axios](https://kubb.dev/extensions/kubb-labs/plugin-axios) guide.
+
+## Skip requests until ready
+
+Set `shouldFetch: false` to give SWR a `null` key and skip the request. Enable it once the required parameters are available. Mutation hooks accept the same switch, and a `null` key stops `trigger` from firing.
+
+```typescript [usage.ts]
+import { useGetPetById } from './gen/hooks/useGetPetById'
+
+export function useSelectedPet(petId: bigint | undefined) {
+  return useGetPetById(
+    { path: { petId: petId ?? 0n } },
+    { shouldFetch: petId != null },
+  )
+}
+```
+
+## Fetch immutable data
+
+Set `immutable: true` on a query hook for data that stays unchanged. It sets `revalidateIfStale`, `revalidateOnFocus`, and `revalidateOnReconnect` to `false`.
+
+```typescript [usage.ts]
+import { useGetPetById } from './gen/hooks/useGetPetById'
+
+const { data, error } = useGetPetById(
+  { path: { petId: 1n } },
+  { immutable: true },
+)
+```
+
+Options in `query` override these revalidation defaults.

package/docs/options.md

@@ -0,0 +1,164 @@
+# Options
+
+Pass these options to `pluginSwr()`, all of them optional. Shared options link to [Shared plugin options](https://kubb.dev/docs/5.x/reference/plugin-options) for details.
+
+## Options overview
+
+| Option                                                                    | Purpose                                                                | Default                                                                       |
+| ------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| [`output`](https://kubb.dev/docs/5.x/reference/plugin-options#output)     | Where files are written: `path`, `mode`, `barrel`, `banner`, `footer`. | `{ path: 'hooks', barrel: { type: 'named' } }`                                |
+| [`group`](https://kubb.dev/docs/5.x/reference/plugin-options#group)       | Split output by tag or path: `type`, `name`.                           | None                                                                          |
+| [`client`](#client)                                                       | Which registered client plugin the hooks call.                         | Auto-detected                                                                 |
+| [`query`](#query)                                                         | Configure the `useSWR` hooks, or turn them off.                        | `{ methods: ['GET'], importPath: 'swr' }`                                     |
+| [`queryKey`](#querykey)                                                   | Build the SWR key for each query hook.                                 | Built-in `queryKeyTransformer`                                                |
+| [`mutation`](#mutation)                                                   | Configure the `useSWRMutation` hooks, or turn them off.                | `{ methods: ['POST', 'PUT', 'PATCH', 'DELETE'], importPath: 'swr/mutation' }` |
+| [`mutationKey`](#mutationkey)                                             | Build the SWR key for each mutation hook.                              | Built-in `mutationKeyTransformer`                                             |
+| [`include`](https://kubb.dev/docs/5.x/reference/plugin-options#include)   | Keep only operations that match.                                       | None                                                                          |
+| [`exclude`](https://kubb.dev/docs/5.x/reference/plugin-options#exclude)   | Skip operations that match.                                            | `[]`                                                                          |
+| [`override`](https://kubb.dev/docs/5.x/reference/plugin-options#override) | Apply different options per pattern.                                   | `[]`                                                                          |
+| [`resolver`](#resolver)                                                   | Customize generated names and file paths.                              | `resolverSwr`                                                                 |
+| [`macros`](https://kubb.dev/docs/5.x/reference/plugin-options#macros)     | Rewrite AST nodes before printing.                                     | `[]`                                                                          |
+
+## Option details
+
+### client
+
+Selects which registered client plugin the hooks call. A single registered client is auto-detected. Set `client` when several are registered.
+
+|          |                      |
+| -------- | -------------------- |
+| Type     | `'fetch' \| 'axios'` |
+| Required | `false`              |
+
+::field-group
+
+:::field{name="'fetch'"}
+Calls the operations generated by [`@kubb/plugin-fetch`](https://kubb.dev/extensions/kubb-labs/plugin-fetch).
+:::
+
+:::field{name="'axios'"}
+Calls the operations generated by [`@kubb/plugin-axios`](https://kubb.dev/extensions/kubb-labs/plugin-axios).
+:::
+
+::
+
+### query
+
+Configures the generated `useSWR` hooks. Pass an object to change the HTTP methods or import path, or `false` to skip query hook generation.
+
+|          |                                           |
+| -------- | ----------------------------------------- |
+| Type     | `Partial<Query> \| false`                 |
+| Required | `false`                                   |
+| Default  | `{ methods: ['GET'], importPath: 'swr' }` |
+
+#### query.methods
+
+HTTP methods treated as queries. An operation whose method is in this list generates a `useSWR` hook instead of a mutation.
+
+|          |                 |
+| -------- | --------------- |
+| Type     | `Array<string>` |
+| Required | `false`         |
+| Default  | `['GET']`       |
+
+#### query.importPath
+
+Module that `useSWR` is imported from, emitted as `import useSWR from '${importPath}'`. Relative and absolute paths are used as written, with relative paths resolved against the generated file.
+
+|          |          |
+| -------- | -------- |
+| Type     | `string` |
+| Required | `false`  |
+| Default  | `'swr'`  |
+
+### queryKey
+
+Builds the SWR key for each query hook. The callback receives the operation `node`, the active `casing` and `variant: 'query'` and returns the key array. Strings are copied into the generated code as written, so wrap a string literal in `JSON.stringify(...)`.
+
+|          |                                                        |
+| -------- | ------------------------------------------------------ |
+| Type     | `(props: { node, casing, variant }) => Array<unknown>` |
+| Required | `false`                                                |
+| Default  | Built-in `queryKeyTransformer`                         |
+
+```typescript
+queryKey: ({ node, variant }) => [JSON.stringify({ variant, operationId: node.operationId })]
+```
+
+### mutation
+
+Configures the generated `useSWRMutation` hooks. Pass an object to change the HTTP methods or import path, or `false` to skip mutation hook generation.
+
+|          |                                                                               |
+| -------- | ----------------------------------------------------------------------------- |
+| Type     | `Partial<Mutation> \| false`                                                  |
+| Required | `false`                                                                       |
+| Default  | `{ methods: ['POST', 'PUT', 'PATCH', 'DELETE'], importPath: 'swr/mutation' }` |
+
+#### mutation.methods
+
+HTTP methods treated as mutations. An operation whose method is in this list generates a `useSWRMutation` hook instead of a query.
+
+|          |                                      |
+| -------- | ------------------------------------ |
+| Type     | `Array<string>`                      |
+| Required | `false`                              |
+| Default  | `['POST', 'PUT', 'PATCH', 'DELETE']` |
+
+#### mutation.importPath
+
+Module that `useSWRMutation` is imported from, emitted as `import useSWRMutation from '${importPath}'`. Relative and absolute paths are used as written, with relative paths resolved against the generated file.
+
+|          |                  |
+| -------- | ---------------- |
+| Type     | `string`         |
+| Required | `false`          |
+| Default  | `'swr/mutation'` |
+
+### mutationKey
+
+Builds the SWR key for each mutation hook. Like `queryKey`, the callback receives the operation `node`, the active `casing` and `variant: 'mutation'` and returns the key array. Strings are copied into the generated code as written, so wrap a string literal in `JSON.stringify(...)`.
+
+|          |                                                        |
+| -------- | ------------------------------------------------------ |
+| Type     | `(props: { node, casing, variant }) => Array<unknown>` |
+| Required | `false`                                                |
+| Default  | Built-in `mutationKeyTransformer`                      |
+
+### resolver
+
+Overrides generated file and symbol names. Omitted members keep `resolverSwr`. The shared members (`name`, `file`, `imports`) and the `this` context are described under [`resolver`](https://kubb.dev/docs/5.x/reference/plugin-options#resolver).
+
+|          |                              |
+| -------- | ---------------------------- |
+| Type     | `ResolverPatch<ResolverSwr>` |
+| Required | `false`                      |
+
+::code-collapse{name="ResolverSwr patch members"}
+
+```typescript [Partial override]
+type ResolverSwrPatch = {
+  name?(name: string): string
+  file?: {
+    baseName?(params: { name: string; extname: string }): string
+    path?(params: { baseName: string; output: Output }): string
+  }
+  imports?(options: ResolveImportsOptions): Array<ImportNode>
+  query?: {
+    name?(node: OperationNode): string         // → 'useGetPetById'
+    optionsName?(node: OperationNode): string  // → 'getPetByIdQueryOptions'
+    keyName?(node: OperationNode): string       // → 'getPetByIdQueryKey'
+    keyTypeName?(node: OperationNode): string   // → 'GetPetByIdQueryKey'
+    clientName?(node: OperationNode): string    // → 'getPetById'
+  }
+  mutation?: {
+    name?(node: OperationNode): string          // → 'useUpdatePet'
+    keyName?(node: OperationNode): string        // → 'updatePetMutationKey'
+    keyTypeName?(node: OperationNode): string    // → 'UpdatePetMutationKey'
+    argTypeName?(node: OperationNode): string    // → 'UpdatePetMutationArg'
+  }
+}
+```
+
+::

package/docs/overview.md

@@ -0,0 +1,39 @@
+# SWR
+
+Generates typed SWR hooks from your OpenAPI spec: `useSWR` for reads and `useSWRMutation` for writes.
+
+The plugin ships no HTTP client. Each hook calls a function generated by a client plugin.
+
+## Setup
+
+- Add `@kubb/plugin-ts` and a client plugin: `@kubb/plugin-fetch` or `@kubb/plugin-axios`.
+- Install SWR v2 or higher in the app that uses the generated code.
+- Configure validation on the client plugin, not here.
+
+## Options worth knowing
+
+- `client` picks `fetch` or `axios` when both client plugins are registered. A single client is detected automatically.
+- `query` and `mutation` set which HTTP methods become queries (`GET`) and mutations (`POST`, `PUT`, `PATCH`, `DELETE`), and where SWR is imported from (`swr` and `swr/mutation`). Set either to `false` to skip it.
+
+## Example
+
+```typescript [kubb.config.ts]
+import { defineConfig } from 'kubb/config'
+import { pluginTs } from '@kubb/plugin-ts'
+import { pluginFetch } from '@kubb/plugin-fetch'
+import { pluginSwr } from '@kubb/plugin-swr'
+
+export default defineConfig({
+  input: './petStore.yaml',
+  output: { path: './src/gen' },
+  plugins: [
+    pluginTs(),
+    pluginFetch(),
+    pluginSwr(),
+  ],
+})
+```
+
+## See also
+
+- [SWR](https://swr.vercel.app)

package/kubb-extension.json

@@ -0,0 +1,200 @@
+{
+  "$schema": "https://kubb.dev/schemas/kubb-extension.json",
+  "kind": "plugin",
+  "name": "plugin-swr",
+  "export": "pluginSwr",
+  "displayName": "SWR",
+  "description": "Generates typed SWR hooks from your OpenAPI spec, so data fetching stays in sync with the API.",
+  "category": "framework",
+  "icon": {
+    "light": "https://kubb.dev/feature/swr.svg"
+  },
+  "tags": ["swr", "react", "hooks", "data-fetching", "codegen", "openapi"],
+  "docs": "https://kubb.dev/extensions/kubb-labs/plugin-swr",
+  "maintainers": [
+    {
+      "name": "Stijn Van Hulle",
+      "github": "stijnvanhulle"
+    }
+  ],
+  "dependencies": ["plugin-ts"],
+  "compatibility": {
+    "kubb": ">=5.8.3",
+    "node": ">=22"
+  },
+  "role": "consumer",
+  "options": [
+    {
+      "key": "outputPath",
+      "path": ["output", "path"],
+      "label": "Output Path",
+      "description": "Output folder for generated files",
+      "type": "text",
+      "default": "hooks"
+    },
+    {
+      "key": "barrel",
+      "path": ["output", "barrel"],
+      "label": "Barrel",
+      "description": "How index.ts barrel files are generated",
+      "type": "select",
+      "default": {
+        "type": "named"
+      },
+      "choices": [
+        {
+          "label": "named",
+          "value": {
+            "type": "named"
+          }
+        },
+        {
+          "label": "named (nested)",
+          "value": {
+            "type": "named",
+            "nested": true
+          }
+        },
+        {
+          "label": "all",
+          "value": {
+            "type": "all"
+          }
+        },
+        {
+          "label": "all (nested)",
+          "value": {
+            "type": "all",
+            "nested": true
+          }
+        },
+        {
+          "label": "false (disabled)",
+          "value": false
+        }
+      ]
+    },
+    {
+      "key": "outputMode",
+      "path": ["output", "mode"],
+      "label": "Output Mode",
+      "description": "How the plugin consolidates its code into files. File mode writes everything into a single file, so the output path must include a file extension and cannot be grouped.",
+      "type": "select",
+      "default": "directory",
+      "choices": [
+        {
+          "label": "directory (one file per schema)",
+          "value": "directory"
+        },
+        {
+          "label": "file (single file)",
+          "value": "file"
+        }
+      ]
+    },
+    {
+      "key": "client",
+      "path": ["client"],
+      "label": "Client",
+      "description": "HTTP client the generated hooks call. Only needed to disambiguate when both plugin-fetch and plugin-axios are enabled",
+      "type": "select",
+      "default": null,
+      "choices": [
+        {
+          "label": "auto-detect",
+          "value": null
+        },
+        {
+          "label": "fetch",
+          "value": "fetch"
+        },
+        {
+          "label": "axios",
+          "value": "axios"
+        }
+      ]
+    },
+    {
+      "key": "group",
+      "path": ["group"],
+      "label": "Group",
+      "description": "Group generated operations by OpenAPI tag or path",
+      "type": "select",
+      "default": null,
+      "choices": [
+        {
+          "label": "none",
+          "value": null
+        },
+        {
+          "label": "by tag",
+          "value": {
+            "type": "tag"
+          }
+        },
+        {
+          "label": "by path",
+          "value": {
+            "type": "path"
+          }
+        }
+      ]
+    },
+    {
+      "key": "excludeTags",
+      "path": ["exclude"],
+      "label": "Exclude Tags",
+      "description": "Comma-separated OpenAPI tags to exclude from generation",
+      "type": "list",
+      "item": {
+        "type": "tag",
+        "pattern": "$item"
+      }
+    },
+    {
+      "key": "includeTags",
+      "path": ["include"],
+      "label": "Include Tags",
+      "description": "Comma-separated OpenAPI tags to include. Only operations with these tags are generated",
+      "type": "list",
+      "item": {
+        "type": "tag",
+        "pattern": "$item"
+      }
+    },
+    {
+      "key": "queryMethods",
+      "path": ["query", "methods"],
+      "label": "Query Methods",
+      "description": "Comma-separated HTTP methods treated as queries (default: GET)",
+      "type": "list",
+      "default": ["GET"],
+      "itemCase": "upper"
+    },
+    {
+      "key": "queryImportPath",
+      "path": ["query", "importPath"],
+      "label": "Query Import Path",
+      "description": "Module specifier the generated query hook imports from",
+      "type": "text",
+      "default": "swr"
+    },
+    {
+      "key": "mutationMethods",
+      "path": ["mutation", "methods"],
+      "label": "Mutation Methods",
+      "description": "Comma-separated HTTP methods treated as mutations (default: POST, PUT, PATCH, DELETE)",
+      "type": "list",
+      "default": ["POST", "PUT", "PATCH", "DELETE"],
+      "itemCase": "upper"
+    },
+    {
+      "key": "mutationImportPath",
+      "path": ["mutation", "importPath"],
+      "label": "Mutation Import Path",
+      "description": "Module specifier the generated mutation hook imports from",
+      "type": "text",
+      "default": "swr/mutation"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/plugin-swr",
-  "version": "5.2.2",
+  "version": "5.2.4",
   "description": "Generate type-safe SWR hooks with Kubb. Covers useSWR and useSWRMutation with full TypeScript support.",
   "keywords": [
     "code-generation",
@@ -15,7 +15,7 @@
     "use-swr",
     "use-swr-mutation"
   ],
-  "homepage": "https://kubb.dev/plugins/plugin-swr",
+  "homepage": "https://kubb.dev/extensions/kubb-labs/plugin-swr",
   "license": "MIT",
   "author": "stijnvanhulle",
   "repository": {
@@ -39,6 +39,8 @@
   ],
   "files": [
     "dist",
+    "kubb-extension.json",
+    "docs",
     "!/**/**.test.**",
     "!/**/__tests__/**",
     "!/**/__snapshots__/**"
@@ -64,25 +66,26 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./kubb-extension.json": "./kubb-extension.json"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/plugin-ts": "^5.0.7"
+    "@kubb/plugin-ts": "^5.0.9"
   },
   "devDependencies": {
     "@internals/client": "0.0.0",
     "@internals/shared": "0.0.0",
     "@internals/tanstack-query": "0.0.0",
     "@internals/utils": "0.0.0",
-    "kubb": "^5.8.0",
+    "kubb": "^5.8.3",
     "swr": "^2.5.1"
   },
   "peerDependencies": {
-    "kubb": "^5.8.0",
+    "kubb": "^5.8.3",
     "swr": "^2.0.0"
   },
   "peerDependenciesMeta": {