hey-api · mrlubos · Aug 25, 2025 · Feb 6, 2025 · Feb 6, 2025 · Mar 23, 2025
diff --git a/.changeset/smooth-ties-brush.md b/.changeset/smooth-ties-brush.md
@@ -0,0 +1,5 @@
+---
+'@hey-api/openapi-ts': patch
+---
+
+feat(plugin): add `@pinia/colada` plugin
diff --git a/packages/openapi-ts-tests/main/test/plugins.test.ts b/packages/openapi-ts-tests/main/test/plugins.test.ts
@@ -363,6 +363,15 @@ for (const version of versions) {
         description:
           'generate Fetch API client with TanStack Vue Query plugin with custom names',
       },
+      // TODO: add Pinia Colada snapshots
+      // {
+      //   config: createConfig({
+      //     output: 'fetch',
+      //     plugins: ['@pinia/colada', '@hey-api/client-fetch'],
+      //   }),
+      //   description:
+      //     'generate Fetch API client with Pinia Colada plugin',
+      // },
       {
         config: createConfig({
           output: 'default',

diff --git a/packages/openapi-ts/src/plugins/@hey-api/typescript/operation.ts b/packages/openapi-ts/src/plugins/@hey-api/typescript/operation.ts
@@ -9,7 +9,8 @@ import { schemaToType } from './plugin';
 import { typesId } from './ref';
 import type { HeyApiTypeScriptPlugin, PluginState } from './types';
 
-const irParametersToIrSchema = ({
+// TODO: exported just for @pinia/colada, remove export once that plugin does not depend on it
+export const irParametersToIrSchema = ({
   parameters,
 }: {
   parameters: Record<string, IR.ParameterObject>;

diff --git a/packages/openapi-ts/src/plugins/@pinia/colada/config.ts b/packages/openapi-ts/src/plugins/@pinia/colada/config.ts
@@ -0,0 +1,26 @@
+import { definePluginConfig } from '../../shared/utils/config';
+import { handler } from './plugin';
+import type { PiniaColadaPlugin } from './types';
+
+export const defaultConfig: PiniaColadaPlugin['Config'] = {
+  config: {
+    enablePaginationOnKey: undefined,
+    errorHandling: 'specific',
+    exportFromIndex: false,
+    groupByTag: false,
+    importPath: '@pinia/colada',
+    includeTypes: true,
+    prefixUse: true,
+    suffixQueryMutation: true,
+    useInfiniteQueries: false,
+  },
+  dependencies: ['@hey-api/typescript'],
+  handler: handler as PiniaColadaPlugin['Handler'],
+  name: '@pinia/colada',
+  output: '@pinia/colada',
+};
+
+/**
+ * Type helper for `@pinia/colada` plugin, returns {@link Plugin.Config} object
+ */
+export const defineConfig = definePluginConfig(defaultConfig);
diff --git a/packages/openapi-ts/src/plugins/@pinia/colada/index.ts b/packages/openapi-ts/src/plugins/@pinia/colada/index.ts
@@ -0,0 +1,2 @@
+export { defaultConfig, defineConfig } from './config';
+export type { PiniaColadaPlugin } from './types';
diff --git a/packages/openapi-ts/src/plugins/@pinia/colada/mutation.ts b/packages/openapi-ts/src/plugins/@pinia/colada/mutation.ts
@@ -0,0 +1,29 @@
+import type { GeneratedFile } from '../../../generate/file';
+import type { IR } from '../../../ir/types';
+import type { PiniaColadaPlugin } from './types';
+import { createComposable } from './utils';
+
+/**
+ * Creates a mutation function for an operation
+ */
+export const createMutationFunction = ({
+  context,
+  file,
+  operation,
+  plugin,
+}: {
+  context: IR.Context;
+  file: GeneratedFile;
+  operation: IR.OperationObject;
+  plugin: PiniaColadaPlugin['Instance'];
+}) => {
+  // Allow hooks to customize or skip mutation generation
+  if (
+    plugin.config.onMutation &&
+    plugin.config.onMutation(operation) === false
+  ) {
+    return;
+  }
+
+  createComposable({ context, file, isQuery: false, operation, plugin });
+};
diff --git a/packages/openapi-ts/src/plugins/@pinia/colada/plugin.ts b/packages/openapi-ts/src/plugins/@pinia/colada/plugin.ts
@@ -0,0 +1,67 @@
+import { clientId } from '../../@hey-api/client-core/utils';
+import { createMutationFunction } from './mutation';
+import { createQueryFunction } from './query';
+import type { PiniaColadaPlugin } from './types';
+import { isQuery } from './utils';
+
+export const handler: PiniaColadaPlugin['Handler'] = ({ plugin }) => {
+  if (!plugin.config.groupByTag) {
+    plugin.createFile({
+      id: plugin.name,
+      path: plugin.output,
+    });
+  }
+
+  // Create files based on grouping strategy
+  const getFile = (tag: string) => {
+    if (!plugin.config.groupByTag) {
+      return (
+        plugin.context.file({ id: plugin.name }) ??
+        plugin.createFile({
+          id: plugin.name,
+          path: plugin.output,
+        })
+      );
+    }
+
+    const fileId = `${plugin.name}/${tag}`;
+    return (
+      plugin.context.file({ id: fileId }) ??
+      plugin.createFile({
+        id: fileId,
+        path: `${plugin.output}/${tag}`,
+      })
+    );
+  };
+
+  plugin.forEach('operation', ({ operation }) => {
+    const file = getFile(operation.tags?.[0] || 'default');
+
+    // Determine if the operation should be a query or mutation
+    if (isQuery(operation, plugin)) {
+      createQueryFunction({ context: plugin.context, file, operation, plugin });
+    } else {
+      createMutationFunction({
+        context: plugin.context,
+        file,
+        operation,
+        plugin,
+      });
+    }
+  });
+
+  // Add client import to all generated files
+  Object.entries(plugin.context.files).forEach(([fileId, file]) => {
+    if (fileId.startsWith(plugin.name)) {
+      // Make sure we have a client import
+      file.import({
+        alias: '_heyApiClient',
+        module: file.relativePathToFile({
+          context: plugin.context,
+          id: clientId,
+        }),
+        name: 'client',
+      });
+    }
+  });
+};
diff --git a/packages/openapi-ts/src/plugins/@pinia/colada/query.ts b/packages/openapi-ts/src/plugins/@pinia/colada/query.ts
@@ -0,0 +1,25 @@
+import type { GeneratedFile } from '../../../generate/file';
+import type { IR } from '../../../ir/types';
+import type { PiniaColadaPlugin } from './types';
+import { createComposable } from './utils';
+
+/**
+ * Creates a query function for an operation
+ */
+export const createQueryFunction = ({
+  context,
+  file,
+  operation,
+  plugin,
+}: {
+  context: IR.Context;
+  file: GeneratedFile;
+  operation: IR.OperationObject;
+  plugin: PiniaColadaPlugin['Instance'];
+}) => {
+  if (plugin.config.onQuery && plugin.config.onQuery(operation) === false) {
+    return;
+  }
+
+  createComposable({ context, file, isQuery: true, operation, plugin });
+};
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		export { defaultConfig, defineConfig } from './config';
		export type { PiniaColadaPlugin } from './types';