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

`ts
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:///server.d.ts
`

If you've customized the path:

`
curl -o server.ts https:///your-custom-path
`

Then use it in your frontend code:

`ts
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('https://')
`

Configuration

The dts plugin accepts the following configuration options:

`ts
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. |

$3

`ts
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.` on separate lines, as the latter approach won't be properly included in type compilation by TypeScript. (example)