Pinia Coladav0

About

Pinia Colada is the perfect companion to Pinia to handle async state management in your Vue applications.

The Pinia Colada plugin for Hey API generates functions and query keys from your OpenAPI spec, fully compatible with SDKs, transformers, and all core features.

Collaborators

• Dmitriy Brolnickij
• Josh Hemphill
• Sebastiaan Wouters

Features

• Pinia Colada v0 support
• seamless integration with @hey-api/openapi-ts ecosystem
• create query keys following the best practices
• type-safe query options and mutation options
• minimal learning curve thanks to extending the underlying technology

Installation

In your configuration, add @pinia/colada to your plugins and you’ll be ready to generate Pinia Colada artifacts. 🎉

openapi-ts.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    '@pinia/colada',
  ],
};

Tip

When using this plugin in a Nuxt app, prefer the ofetch client for universal compatibility.

The nuxt client is tailored for working directly with Nuxt composables ($fetch / useFetch / useAsyncData) and is not intended as a universal HTTP client for libraries like @pinia/colada.

Output

The Pinia Colada plugin will generate the following artifacts, depending on the input specification.

Queries

Queries are generated from query operations. The generated query functions follow the naming convention of SDK functions and by default append Query, e.g., getPetByIdQuery().

example

colada.gen.ts

const query = useQuery(getPetByIdQuery, () => ({
  path: {
    petId: 1,
  },
}));

config

openapi-ts.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: '@pinia/colada',
      queryOptions: true,
    },
  ],
};

You can customize the naming and casing pattern for queryOptions functions using the .name and .case options.

Query Keys

Query keys contain normalized SDK function parameters and additional metadata.

example

colada.gen.ts

const queryKey = [
  {
    _id: 'getPetById',
    baseUrl: 'https://app.heyapi.dev',
    path: {
      petId: 1,
    },
  },
];

config

openapi-ts.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: '@pinia/colada',
      queryKeys: true,
    },
  ],
};

Tags

You can include operation tags in your query keys by setting tags to true. This will make query keys larger but provides better cache invalidation capabilities.

example

colada.gen.ts

const key = [
  {
    _id: 'getPetById',
    baseUrl: 'https://app.heyapi.dev',
    path: {
      petId: 1,
    },
    tags: ['pets', 'one', 'get'],
  },
];

config

openapi-ts.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: '@pinia/colada',
      queryKeys: {
        tags: true,
      },
    },
  ],
};

Accessing Query Keys

If you have access to the result of query options function, you can get the query key from the key field.

example

colada.gen.ts

const { key } = getPetByIdQuery({
  path: {
    petId: 1,
  },
});

config

openapi-ts.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: '@pinia/colada',
      queryOptions: true,
    },
  ],
};

Alternatively, you can access the same query key by calling query key functions. The generated query key functions follow the naming convention of SDK functions and by default append QueryKey, e.g., getPetByIdQueryKey().

example

colada.gen.ts

const key = getPetByIdQueryKey({
  path: {
    petId: 1,
  },
});

config

openapi-ts.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: '@pinia/colada',
      queryKeys: true,
    },
  ],
};

You can customize the naming and casing pattern for queryKeys functions using the .name and .case options.

Mutations

Mutations are generated from mutation operations. The generated mutation functions follow the naming convention of SDK functions and by default append Mutation, e.g., addPetMutation().

example

colada.gen.ts

const addPet = useMutation({
  ...addPetMutation(),
  onError: (error) => {
    console.log(error);
  },
});

addPet.mutate({
  body: {
    name: 'Kitty',
  },
});

config

openapi-ts.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: '@pinia/colada',
      mutationOptions: true,
    },
  ],
};

You can customize the naming and casing pattern for mutationOptions functions using the .name and .case options.

API

You can view the complete list of options in the UserConfig interface.

Examples

You can view live examples on StackBlitz or on GitHub.