Elysia Remote DTS

A plugin that provides remote .d.ts types for Eden Treaty to consume.

Problem

Imagine this scenario: You've deployed an Elysia server remotely and want to provide end-to-end type safety using Eden Treaty. However, external developers don't have direct access to your server's source code to extract the typeof app types because:

• Your server is closed-source
• The frontend is located elsewhere, making types inaccessible

This plugin solves this problem by exposing types remotely and providing them to Eden Treaty for consumption.

[!NOTE]
The code responsible for runtime type-generation is adapted from rolldown-plugin-dts. The difference is that our generateDts utility is completely independent and decoupled from the rolldown lifecycle. Full credit goes to the original developers - we've simply ported some functionality to enhance the Elysia ecosystem.

Installation

bun add elysia-remote-dts

Usage

import { Elysia } from 'elysia'
import { dts } from 'elysia-remote-dts'

const app = new Elysia().use(dts('./src/index.ts')).listen(3000)

// Be sure to export the type for the plugin to consume
export type App = typeof app;

Types will then be available at /server.d.ts by default, or at the path specified in the dtsPath option.

Due to limitations with Triple-Slash Directives, types cannot be directly consumed from a remote URL (tracking issue). For frontend projects, you'll need to first download the type declaration file before using it with Eden:

curl -o server.ts https://<remote-url>/server.d.ts

If you've customized the path:

curl -o server.ts https://<remote-url>/your-custom-path

Then use it in your frontend code:

import { treaty } from '@elysiajs/eden'
import type { App } from './server'

// Your frontend project should already have both elysia and @elysiajs/eden installed
export const app = treaty<App>('https://<remote-url>')

Configuration

The dts plugin accepts the following configuration options:

dts(entryPoint, options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | cwd | string | Current directory | The directory where the plugin will look for the tsconfig.json file. | | dtsInput | boolean | false | Set to true when entries are .d.ts files (instead of .ts files). When enabled, the plugin will skip generating a .d.ts file for the entry point. | | tsconfig | string \| boolean | "tsconfig.json" | The path to the tsconfig.json file. When set to false, any tsconfig.json file will be ignored. | | compilerOptions | object | {} | The compilerOptions for the TypeScript compiler. See TypeScript compiler options. | | resolve | boolean \| (string \| RegExp)[] | false | Resolve external types used in .d.ts files from node_modules. Can be a boolean or an array of strings/RegExp patterns. | | resolvePaths | boolean | false | When true, the plugin will resolve paths in tsconfig.json. This option is enabled automatically when paths is set in compilerOptions. | | dtsPath | string | "/server.d.ts" | The path where the type definitions will be served. |

Example with Options

import { Elysia } from 'elysia'
import { dts } from 'elysia-remote-dts'

const app = new Elysia().use(
  dts('./src/index.ts', {
    tsconfig: './tsconfig.json',
    compilerOptions: {
      strict: true
    },
    dtsPath: '/types.d.ts'
  })
).listen(3000)

export type App = typeof app;

Known Limitations

1. Type emission may occasionally return null in certain runtime environments (particularly in Distroless). We recommend using oven/bun or oven/bun:alpine as your base image.

2. The typescript package must be available at runtime, not just as a development dependency.

3. For all Elysia instances and controller chaining, it's recommended to chain your routes rather than calling controller.<METHOD> on separate lines, as the latter approach won't be properly included in type compilation by TypeScript. (example)