Aspida

Common errors

• Cannot find module '../api/$api' or its corresponding type declarations.

  cause The Aspida API client definition file `$api.ts` has not been generated, or the import path is incorrect.
  fix Ensure you have `"api:build": "aspida"` in your `package.json` scripts, then run `npm run api:build`. Verify the import path `../api/$api` matches the location where `aspida` generates the file.

• TypeError: api is not a function

  cause The `api` object imported from the generated `$api.ts` is not being called as a factory function with an Aspida adapter, or the adapter itself is missing/incorrect.
  fix Ensure you are initializing the client correctly with `const client = api(aspida());`. Make sure `@aspida/axios` (or your chosen adapter) is installed and imported as `aspida`.

• Property 'v1' does not exist on type '(...)'

  cause This typically means there's a mismatch between the expected API structure in your code and what was generated by Aspida, or the generated `$api.ts` file is outdated.
  fix Double-check your `api` directory structure against how you are accessing the client (e.g., `client.v1.users`). Re-run `npm run api:build` to ensure the client reflects the latest directory definitions.

Warnings

• breaking Aspida moved the core `aspida` package to a peerDependency in v1.14.0. This means you must explicitly install `aspida` alongside any `@aspida/*` adapter packages. Previously, it might have been implicitly installed.
  Fix: Ensure `aspida` is listed in your project's `dependencies` or `devDependencies` (`npm install aspida` or `yarn add aspida`).
• breaking Starting with v1.14.0, import names for generated client files changed their postfix to a hash (`#`). This could affect existing import statements that relied on the previous naming convention for generated type definition files.
  Fix: Review and update your import paths for generated files (e.g., `../api/$api` might change if the postfix convention affects the top-level generated file directly, or internal generated types). Re-run `npm run api:build` and inspect the generated `$api.ts` file for new import patterns.
• gotcha The Aspida CLI requires a build step (`npm run api:build`) to generate the `$api.ts` type definition file based on your `api` directory structure. Forgetting this step or not having it configured will result in missing module errors.
  Fix: Add `"api:build": "aspida"` to your `package.json` scripts and run `npm run api:build` before starting your application development or build process.
• gotcha When defining path variables, specifying the type (e.g., `_userId@number`) is crucial. If omitted (e.g., `_userId/`), the path variable type defaults to `number | string`, which might be less specific than intended and lead to weaker type checking.
  Fix: Always specify the type of path variables explicitly using the `@type` postfix (e.g., `_id@string`, `_postId@number`) in your API directory structure.

Install

• npm install aspida npm
• yarn add aspida yarn
• pnpm add aspida pnpm

Imports

• DefineMethods
  wrong:

  const { DefineMethods } = require('aspida');

  correct:

  import type { DefineMethods } from 'aspida';

  This is a type-only import for defining API endpoint methods.
• api
  wrong:

  const api = require('../api/$api');

  correct:

  import api from '../api/$api';

  The `api` symbol is the generated client entry point from your `api` directory. The path depends on your project structure.
• aspida
  wrong:

  const aspida = require('@aspida/axios');

  correct:

  import aspida from '@aspida/axios';

  This imports the adapter factory function for Axios. Use `@aspida/fetch` or `@aspida/node-fetch` for other HTTP clients.

Quickstart

Demonstrates how to install Aspida with the Axios adapter, define API endpoints, generate type-safe client code, and make various HTTP requests using the generated client.

import aspida from '@aspida/axios';
import api from '../api/$api'; // This file is generated by 'npm run api:build'

// Ensure this directory structure is created and 'aspida' command is run:
// api/
// ├── v1/
// │   ├── users/
// │   │   ├── index.ts
// │   │   └── _userId@number/
// │   │       └── index.ts
// package.json: { "scripts": { "api:build": "aspida" } }

// Example: api/v1/users/index.ts
// import type { DefineMethods } from "aspida";
// type User = { id: number; name: string; };
// export type Methods = DefineMethods<{
//   get: { query?: { limit: number; }; resBody: User[]; };
//   post: { reqBody: { name: string; }; resBody: User; };
// }>;

(async () => {
  const userId = 0;
  const limit = 10;
  const client = api(aspida()); // Initialize the client with the Axios adapter

  try {
    // Example: POST /v1/users
    const newUser = await client.v1.users.post({ body: { name: 'aspida-user' } });
    console.log('Created user:', newUser.body);

    // Example: GET /v1/users?limit=10
    const users = await client.v1.users.get({ query: { limit } });
    console.log('Users list:', users.body);

    // Example: GET /v1/users/0
    const userById = await client.v1.users._userId(userId).$get();
    console.log('User by ID:', userById.body);

  } catch (error) {
    console.error('API request failed:', error);
  }
})();