Install the router and Configure tsConfig.json to enable runTypes metadata.
npm i @mionjs/core @mionjs/router
npm i -D @mionjs/devtools
{
"compilerOptions": {
// typescript compiler options ...
},
// enables runtime type metadata for mion's validation and serialization
"reflection": true
}
Install dependencies depending on where you running mion.
For local development use Node or Bun.
npm install @mionjs/platform-node
npm install @mionjs/platform-bun
npm install @mionjs/platform-aws
npm install @mionjs/platform-gcloud
Write your first mion API.
import {HeadersSubset, RpcError} from '@mionjs/core';
import {RouterOptions, initMionRouter, headersFn, middleFn, route} from '@mionjs/router';
export type User = {id: string; name: string; surname: string};
// set options and init router
export const routerOptions: Partial<RouterOptions> = {prefix: 'api/v1'};
export const myApi = await initMionRouter(
// all function parameters will be automatically validated before the function is called
{
auth: headersFn((ctx, h: HeadersSubset<'Authorization'>): void | RpcError<'not-authorized'> => {
const token = h.headers.Authorization;
if (!token) return new RpcError<'not-authorized'>({publicMessage: 'Not Authorized', type: 'not-authorized'});
}),
users: {
sayHello: route((ctx, user: User): string => `Hello ${user.name} ${user.surname}`),
},
log: middleFn((ctx): void => console.log(Date.now(), ctx.path, ctx.response.statusCode), {runOnError: true}),
},
routerOptions
);
// Export the type of the Api (used by the client)
export type MyApi = typeof myApi;
Write a start script depending on where you running mion.
import {NodeHttpOptions, startNodeServer} from '@mionjs/platform-node';
import './myApi.routes';
// init a http server with options specific for node
const nodeOptions: Partial<NodeHttpOptions> = {port: 3000};
startNodeServer(nodeOptions);
import {BunHttpOptions, startBunServer} from '@mionjs/platform-bun';
import './myApi.routes';
// init a bun server with options specific for bun
const bunOptions: Partial<BunHttpOptions> = {port: 3000};
startBunServer(bunOptions);
import {AwsLambdaOptions, createAwsLambdaHandler} from '@mionjs/platform-aws';
import './myApi.routes';
// set options specific for aws lambda
const awsOptions: Partial<AwsLambdaOptions> = {};
// export AWS Lambda Handler
export const handler = createAwsLambdaHandler(awsOptions);
import {GoogleCFOptions, createGoogleCFHandler} from '@mionjs/platform-gcloud';
import './myApi.routes';
// set options specific for GC Cloud Functions
const gcfOptions: Partial<GoogleCFOptions> = {};
// export Google Cloud Functions Handler
export const handler = createGoogleCFHandler(gcfOptions);
npm install @mionjs/client
Make sure to only import the types of our mion API, this way no code is actually imported.
import {initClient} from '@mionjs/client';
// importing only the RemoteApi type from server
import type {MyApi} from './myApi.routes.ts';
const john = {id: '123', name: 'John', surname: 'Doe'};
const {routes, middleFns} = initClient<MyApi>({baseURL: 'http://localhost:3000'});
// prefills auth token for any future requests, value is stored in localStorage by default
await middleFns.auth({headers: {Authorization: 'myToken-XYZ'}}).prefill();
// calls sayHello route in the server
const [hello] = await routes.users.sayHello(john).call();
console.log(hello); // Hello John Doe
// validate parameters locally without calling the server (await still required as typeErrors is async)
const [_, error] = await routes.users.sayHello(john).typeErrors();
console.log(error); // {hasErrors: false, totalErrors: 0, errors: []}