SolidStart

Start by providing an OpenAPI specification and an Orval config file. To use SolidStart, define the client in the Orval config to be solid-start.

Example with SolidStart

1import { defineConfig } from 'orval';
2
3export default defineConfig({
4  petstore: {
5    output: {
6      mode: 'tags-split',
7      target: 'src/petstore.ts',
8      schemas: 'src/model',
9      client: 'solid-start',
10      mock: true,
11    },
12    input: {
13      target: './petstore.yaml',
14    },
15  },
16});

Navigate to the Orval config reference to see all available options.

The SolidStart mode will generate an implementation file using native SolidStart primitives from @solidjs/router.

For example, this Swagger specification will generate the following code:

1import { query, action, revalidate } from '@solidjs/router';
2
3export const SwaggerPetstore = {
4  listPets: query(async (params: ListPetsParams) => {
5    const queryString = new URLSearchParams(params as any).toString();
6    const url = queryString ? `/pets?${queryString}` : `/pets`;
7    const response = await fetch(url, {
8      method: 'GET',
9      headers: { 'Content-Type': 'application/json' }
10    });
11    if (!response.ok) {
12      throw new Error(`HTTP error! status: ${response.status}`);
13    }
14    return response.json() as Promise<Pets>;
15  }, "listPets"),
16
17  createPets: action(async (createPetsBody: CreatePetsBody) => {
18    const response = await fetch('/pets', {
19      method: 'POST',
20      headers: { 'Content-Type': 'application/json' },
21      body: JSON.stringify(createPetsBody)
22    });
23    if (!response.ok) {
24      throw new Error(`HTTP error! status: ${response.status}`);
25    }
26    return response.json() as Promise<Pet>;
27  }, "createPets"),
28
29  showPetById: query(async (petId: string) => {
30    const response = await fetch(`/pets/${petId}`, {
31      method: 'GET',
32      headers: { 'Content-Type': 'application/json' }
33    });
34    if (!response.ok) {
35      throw new Error(`HTTP error! status: ${response.status}`);
36    }
37    return response.json() as Promise<Pet>;
38  }, "showPetById"),
39};

Using the Generated Code

Basic Usage

1import { createAsync } from '@solidjs/router';
2import { Suspense } from 'solid-js';
3import { SwaggerPetstore } from './petstore';
4
5function PetDetails(props: { petId: string }) {
6  // Use createAsync to consume the query - automatically caches based on petId
7  const pet = createAsync(() => SwaggerPetstore.showPetById(props.petId));
8
9  return (
10    <Suspense fallback={<div>Loading...</div>}>
11      <div>
12        <h1>{pet()?.name}</h1>
13        <p>ID: {pet()?.id}</p>
14      </div>
15    </Suspense>
16  );
17}

Cache Invalidation

SolidStart's query() function automatically generates cache keys from the function name and arguments, enabling granular cache invalidation:

1import { revalidate } from '@solidjs/router';
2import { SwaggerPetstore } from './petstore';
3
4// Invalidate a specific pet by ID
5revalidate(SwaggerPetstore.showPetById.keyFor("pet-123"));
6
7// Invalidate all pets
8revalidate(SwaggerPetstore.listPets.key);
9
10// Invalidate multiple specific queries
11revalidate([
12  SwaggerPetstore.showPetById.keyFor("pet-123"),
13  SwaggerPetstore.showPetById.keyFor("pet-456"),
14  SwaggerPetstore.listPets.key,
15]);

Practical Example: Refresh Button

1import { createAsync } from '@solidjs/router';
2import { revalidate } from '@solidjs/router';
3import { Suspense } from 'solid-js';
4import { SwaggerPetstore } from './petstore';
5
6function PetDetails(props: { petId: string }) {
7  const pet = createAsync(() => SwaggerPetstore.showPetById(props.petId));
8
9  const handleRefresh = () => {
10    // Invalidate this specific pet's cache to trigger a refetch
11    revalidate(SwaggerPetstore.showPetById.keyFor(props.petId));
12  };
13
14  return (
15    <Suspense fallback={<div>Loading...</div>}>
16      <div>
17        <h1>{pet()?.name}</h1>
18        <p>ID: {pet()?.id}</p>
19        <button onClick={handleRefresh}>
20          Refresh Pet Data
21        </button>
22      </div>
23    </Suspense>
24  );
25}

Using Actions

Actions are used for mutations (POST, PUT, PATCH, DELETE). You can use them directly with forms or programmatically with useAction():

With Forms

1import { SwaggerPetstore } from './petstore';
2
3function CreatePetForm() {
4  return (
5    <form action={SwaggerPetstore.createPets} method="post">
6      <input name="name" required />
7      <input name="tag" />
8      <button type="submit">Create Pet</button>
9    </form>
10  );
11}

Note: When using actions with forms, you may need to adapt the generated actions to accept FormData instead of typed parameters.

Programmatically with useAction

1import { useAction } from '@solidjs/router';
2import { SwaggerPetstore } from './petstore';
3
4function DeletePetButton(props: { petId: string }) {
5  const deletePet = useAction(SwaggerPetstore.deletePetById);
6
7  const handleDelete = async () => {
8    await deletePet(props.petId);
9    // Actions automatically revalidate all active queries on the page
10  };
11
12  return (
13    <button onClick={handleDelete}>
14      Delete Pet
15    </button>
16  );
17}

Key Features

Native Fetch API

SolidStart client uses the native Fetch API without any HTTP client dependencies:

• Automatic query parameter serialization via URLSearchParams
• JSON request/response handling
• Proper error handling with response.ok checks
• Full TypeScript type safety

Automatic Cache Management

• Queries (query()) are automatically cached based on the function name and arguments
• Actions (action()) are not cached and always execute fresh
• Use .key to get the base cache key for all calls to a query
• Use .keyFor(...args) to get the cache key for a specific set of arguments

SolidStart Primitives

• query() - For GET requests, automatically cached and reactive
• action() - For mutations (POST, PUT, PATCH, DELETE)
• cache() - Advanced caching (available via import)
• revalidate() - Manual cache invalidation

Custom HTTP Client (Mutator)

You can use a custom HTTP client with the mutator configuration:

1import { defineConfig } from 'orval';
2
3export default defineConfig({
4  petstore: {
5    output: {
6      target: 'src/petstore.ts',
7      client: 'solid-start',
8      override: {
9        mutator: {
10          path: './custom-instance.ts',
11          name: 'customInstance',
12        },
13      },
14    },
15    input: {
16      target: './petstore.yaml',
17    },
18  },
19});

This will generate code that uses your custom instance:

1export const SwaggerPetstore = {
2  showPetById: query(async (petId: string) => {
3    return customInstance<Pet>(
4      { url: `/pets/${petId}`, method: 'GET' },
5      fetch,
6    );
7  }, "showPetById"),
8};

Differences from Solid Query

SolidStart is a meta-framework for SolidJS with strong opinions about application architecture. It uses Solid Router under the hood, which provides built-in data primitives for queries and actions.

If you are using SolidStart, it's highly recommended to use its built-in primitives (query() and action() from @solidjs/router) instead of Solid Query. These primitives are designed to work seamlessly with SolidStart's server-side rendering, routing, and caching systems.

Choose SolidStart client when building a SolidStart application. Choose Solid Query client only if you're building a standalone SolidJS app without the SolidStart framework and need advanced TanStack Query features like optimistic updates, background refetching, and complex caching strategies.

Go here for a full example (coming soon)