Registry / http-networking / aspida

aspida

JSON →
library1.14.0jsnpmunverified

Aspida is a TypeScript-friendly HTTP client wrapper designed for both browser and Node.js environments. It streamlines API client generation by enabling developers to define API endpoint types through a convention-over-configuration approach, leveraging a directory structure and `DefineMethods` type aliases. This approach significantly enhances type safety for API interactions at compile time, eliminating the need for manual client creation. Aspida supports integration with popular HTTP clients like Axios, Fetch, and Node-Fetch via official adapter packages. The current stable version is 1.14.0, and the project demonstrates an active release cadence with frequent updates. Its key differentiators include robust type inference for paths, query parameters, headers, request bodies, and responses, comprehensive support for `FormData` and `URLSearchParams`, and a unique workflow that generates a fully type-safe client based on a filesystem-defined API structure.

npm install aspida
INSTALL
IMPORT
SIG · ASPIDA
A
aspida
http-networkingjavascriptv1.14.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

DefineMethods
import type { DefineMethods } from 'aspida';
const { DefineMethods } = require('aspida');
This is a type-only import for defining API endpoint methods.
api
import api from '../api/$api';
const api = require('../api/$api');
The `api` symbol is the generated client entry point from your `api` directory. The path depends on your project structure.
aspida
import aspida from '@aspida/axios';
const aspida = require('@aspida/axios');
This imports the adapter factory function for Axios. Use `@aspida/fetch` or `@aspida/node-fetch` for other HTTP clients.

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); } })();
Debug
Known issues
breakingAspida 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`).
affects: >=1.14.0
breakingStarting 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.
affects: >=1.14.0
gotchaThe 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.
affects: >=1.0.0
gotchaWhen 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.
affects: >=1.0.0
Errors
Common errors & fixes
Cannot find module '../api/$api' or its corresponding type declarations.
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
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 '(...)'
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.
Upgrade
Version history
1.14.0latest on npm
Audit
Dependencies
@aspida/axiosrequiredRequired to use Axios as the underlying HTTP client for making requests.
axiosrequiredThe actual HTTP client library utilized by the `@aspida/axios` adapter.
Agent activity
49 hits · last 30 days
node
42
OpenAI (training)
1
Resources