Quick Start

Server Side

npm i -D @deepkit/type-compiler

Configure tsConfig.json

tsConfig.json
{
  "compilerOptions": {
    // typescript compiler options ...
  },
  // custom flag required by @deepkit/type-compiler
  "reflection": true
}
  • Install dependencies.
npm i @mionkit/router @mionkit/common @deepkit/type
  • Install dependencies depending on where you running mion.
    For local development use Node or Bun.

Node
npm install @mionkit/http
Bun
npm install @mionkit/bun
AWS Lambda
npm install @mionkit/aws
Google Cloud Functions
npm install @mionkit/gcloud

  • Write your first mion API.
myApi.routes.ts
import {RpcError} from '@mionkit/core';
import {RouterOptions, initMionRouter, headersHook, hook, route} from '@mionkit/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 = initMionRouter(
    // all function parameters will be automatically validated before the function is called
    {
        auth: headersHook('authorization', (ctx, token: string): void => {
            if (!token) throw new RpcError({statusCode: 401, message: 'Not Authorized'});
        }),
        users: {
            sayHello: route((ctx, user: User): string => `Hello ${user.name} ${user.surname}`),
        },
        log: hook((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.

Node
import {NodeHttpOptions, startNodeServer} from '@mionkit/http';
import './myApi.routes';

// init a http server with options specific for node
const nodeOptions: Partial<NodeHttpOptions> = {port: 3000};
startNodeServer(nodeOptions);
Bun
import {BunHttpOptions, startBunServer} from '@mionkit/bun';
import './myApi.routes';

// init a bun server with options specific for bun
const bunOptions: Partial<BunHttpOptions> = {port: 3000};
startBunServer(bunOptions);
AWS Lambda
import {AwsLambdaOptions, awsLambdaHandler, setAwsLambdaOpts} from '@mionkit/aws';
import './myApi.routes';

// set options specific for aws lambda
const awsOptions: Partial<AwsLambdaOptions> = {};
setAwsLambdaOpts(awsOptions);

// export AWS Lambda Handler
export const handler = awsLambdaHandler;
Google Cloud Functions
import {GoogleCFOptions, googleCFHandler, setGoogleCFOpts} from '@mionkit/gcloud';
import './myApi.routes';

// set options specific for GC Cloud Functions
const gcfOptions: Partial<GoogleCFOptions> = {};
setGoogleCFOpts(gcfOptions);

// export Google Cloud Functions Handler
export const handler = googleCFHandler;

Client Side

  • Install client side dependencies.
npm install @mionkit/client
  • Use your API.

To consume a Type Safe API we just need to import the type of our mion API so no code from the API is actually imported.

import {initClient} from '@mionkit/client';
// importing only the RemoteApi type from server
import type {MyApi} from './server.routes';

const john = {id: '123', name: 'John', surname: 'Doe'};
const {routes, hooks} = initClient<MyApi>({baseURL: 'http://localhost:3000'});

// prefills auth token for any future requests, value is stored in localStorage by default
await hooks.auth('myToken-XYZ').prefill();

// calls sayHello route in the server
const sayHello = await routes.users.sayHello(john).call();
console.log(sayHello); // Hello John Doe

// validate parameters locally without calling the server (await still required as validate is async)
const validationResp = await routes.users.sayHello(john).validate();
console.log(validationResp); // {hasErrors: false, totalErrors: 0, errors: []}
Table of Contents