@jsheaven/astro-client-generator

@jsheaven/astro-client-generator

Generates TypeScript API client code for your Astro endpoints. No manual fetch() code writing anymore.

User Stories

1. As an Astro developer, I don't want to write the fetch() code for my Astro endpoints manually

2. 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'

// https://astro.build/config
export default defineConfig({
  ...
  integrations: [
    // generate client API code for the endpoints
    apiClientGenerator(),
  ]
})

You can enhance and customize this configuration:

import { apiClientGenerator } from '@jsheaven/astro-client-generator'

// https://astro.build/config
export default defineConfig({
  ...
  integrations: [
    apiClientGenerator({

      // == all settings displayed here are optional. What you see here, are default values ==

      /** folder to the API directory on disk (source code) */
      root: './src/pages/api',
      /** API base URL for calling the API (only relevant if you host in a subdir, it's unlikely) */
      baseUrl: '',
      /** folder on disk to write the client code to */
      outDir: './src/pages/api-client',
       /** parser to use. 'naive' comes with constraints (non-standard-compliant), 'baseline' is 900x slower */
      parser: 'naive',
      /** path to your tsconfig.json, from the root folder of your project */
      tsConfigPath: './tsconfig.json',
    }),
  ]
})

Example usage (API, as a library)

ESM

import { generateClientApis } from '@jsheaven/astro-client-generator'

const result = await generateClientApis({
  // all optional, these are just the default values
  root: './src/pages/api',
  baseUrl: '',
  outDir: './src/pages/api-client',
  parser: 'naive',
  tsConfigPath: './tsconfig.json',
})

CommonJS

const { generateClientApis } = require('@jsheaven/astro-client-generator')

// same API like ESM variant

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'

// https://astro.build/config
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.