@jsheaven/astro-client-generator
Generates TypeScript API client code for your Astro endpoints. No manual fetch()
code writing anymore.
User Stories
-
As an Astro developer, I don't want to write the fetch()
code for my Astro endpoints manually
-
As an Astro developer, I want type-safety and auto-complete in my IDE when calling my Astro endpoints.
Features
- ✅ Generates TypeScript/JavaScript API clients for Astro endpoints (
get
, post
, del
, all
, etc.) - ✅ Available as a simple Astro integration, API and simple to use CLI (for testing and npm scripts)
- ✅ Uses
fetch
under the hood, therefore works isomorphic in browser and in SSR/SSG - ✅ Comes with two parsers:
naive
(highly optimized) and baseline
(deoptimization, safer) - ✅ Just
2.64 kb
nano sized library - ✅
0 byte
runtime overhead/dependencies as it just generates vanilla TS/JS code - ✅ Tree-shakable and side-effect free
- ✅ Runs on Windows, Mac, Linux, CI tested
- ✅ First class TypeScript support
- ✅ 100% Unit Test coverage
Example usage / test it (CLI)
If you want to test it, simply run this command in your Astro project root folder:
npx @jsheaven/astro-client-generator generate
You need at least version 18 of Node.js installed.
Use the Astro intergration
Setup
- yarn:
yarn add @jsheaven/astro-client-generator
- npm:
npm install @jsheaven/astro-client-generator
Integrate into Astro
Add the following code to your astro.config.(js|ts)
:
import { apiClientGenerator } from '@jsheaven/astro-client-generator'
export default defineConfig({
...
integrations: [
apiClientGenerator(),
]
})
You can enhance and customize this configuration:
import { apiClientGenerator } from '@jsheaven/astro-client-generator'
export default defineConfig({
...
integrations: [
apiClientGenerator({
root: './src/pages/api',
baseUrl: '',
outDir: './src/pages/api-client',
parser: 'naive',
tsConfigPath: './tsconfig.json',
}),
]
})
Example usage (API, as a library)
ESM
import { generateClientApis } from '@jsheaven/astro-client-generator'
const result = await generateClientApis({
root: './src/pages/api',
baseUrl: '',
outDir: './src/pages/api-client',
parser: 'naive',
tsConfigPath: './tsconfig.json',
})
CommonJS
const { generateClientApis } = require('@jsheaven/astro-client-generator')
Naive parser pros & cons
The naive
parser in this package is a hand-written, highly optimized parser that is
capable of handling a subset of the official TypeScript / JavaScript syntax.
In naive
parsing mode, code generation will happen in 2 to 5ms
per endpoint,
file in baseline
mode, you can espect at least 1 sec
per endpoint. This is,
why naive
parsing is the default configuration.
If you follow the following rules, the naive
parser should be just working fine:
- write
import
statements in a single line - write
type
definitions in a single line - don't use
{
and }
inside of comments in interface
definitions - endpoints must either be declared as async function expressions like
export const get = ( ... ) => { ... }
- or as an async function
async function get ( ... ) { ... }
- any endpoint method (
get
, post
, del
, etc. that Astro supports, is supported), but keep the method name lowercase
However, if you're running into errors, please use the baseline
parser:
import { apiClientGenerator } from '@jsheaven/astro-client-generator'
export default defineConfig({
...
integrations: [
apiClientGenerator({
...
parser: 'baseline',
...
}),
]
})
Please take a look at the test fixtures to get an idea about what syntax is definitely supported. It should cover most of the simple and advanced use-cases.