Quick Start

Server Side

  • Install dependencies.
npm i -D @deepkit/core @deepkit/type-compiler
npm i @deepkit/core @mionkit/router @mionkit/common
  • 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/serverless

tsconfig.json
{
  "compilerOptions": {
    // typescript compiler options ...
  },
  "reflection": true
}
  • Write your first mion API.
myApi.routes.ts
import {RpcError} from '@mionkit/core';
import {Routes, RouterOptions, initRouter, registerRoutes} from '@mionkit/router';
import {clientRoutes} from '@mionkit/common';

export type User = {id: string; name: string; surname: string};
export type Order = {id: string; date: Date; userId: string; totalUSD: number};

export const routes = {
    auth: {
        headerName: 'authorization',
        hook: (ctx, token: string): void => {
            if (!token) throw new RpcError({statusCode: 401, message: 'Not Authorized', name: ' Not Authorized'});
        },
    },
    users: {
        getById: (ctx, id: string): User => ({id, name: 'John', surname: 'Smith'}),
        delete: (ctx, id: string): string => id,
        create: (ctx, newUser: Omit<User, 'id'>): User => ({id: 'USER-123', ...newUser}),
    },
    orders: {
        getById: (ctx, id: string): Order => ({id, date: new Date(), userId: 'USER-123', totalUSD: 120}),
        delete: (ctx, id: string): string => id,
        create: (ctx, newOrder: Omit<Order, 'id'>): Order => ({id: 'ORDER-123', ...newOrder}),
    },
    utils: {
        sum: (ctx, a: number, b: number): number => a + b,
        sayHello: (ctx, user: User): string => `Hello ${user.name} ${user.surname}`,
    },
    log: {
        forceRunOnError: true,
        hook: (ctx): void => {
            const now = Date.now();
            console.log(now, ctx.path, ctx.response.statusCode);
            if (ctx.request.internalErrors.length) console.error(now, ctx.path, ctx.request.internalErrors);
        },
    },
} satisfies Routes;

// set options and init router
export const routerOptions: Partial<RouterOptions> = {prefix: 'api/v1'};
initRouter(routerOptions);

// register routes and exporting the type of the Api (used by the client)
export const myApi = registerRoutes(routes);
export type MyApi = typeof myApi;

// register routes required by client
// these routes serve metadata required for validation and serialization on the client
registerRoutes(clientRoutes);
  • Write a start script depending on where you running mion.

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

// set options specific for node
const nodeOptions: Partial<NodeHttpOptions> = {port: 8080};
setNodeHttpOpts(nodeOptions);

// init node server
startNodeServer();
Bun
import {BunHttpOptions, setBunHttpOpts, startBunServer} from '@mionkit/bun';
import './myApi.routes';

// set options specific for bun
const bunOptions: Partial<BunHttpOptions> = {port: 8080};
setBunHttpOpts(bunOptions);

// init bun server
startBunServer();
AWS Lambda
import {AwsLambdaOptions, awsLambdaHandler, setAwsLambdaOpts} from '@mionkit/serverless';
import './myApi.routes';

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

// export AWS Lambda Handler
export const handler = awsLambdaHandler;

Client Side

  • Install client dependencies.
npm install @mionkit/client
  • Use your API.
import {initClient} from '@mionkit/client';

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

const port = 8076;
const baseURL = `http://localhost:${port}`;
const {routes, hooks} = initClient<MyApi>({baseURL});

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

// calls sayHello route in the server
const sayHello = await routes.utils.sayHello({id: '123', name: 'John', surname: 'Doe'}).call();
console.log(sayHello); // Hello John Doe

// calls sumTwo route in the server
const sumTwoResp = await routes.utils.sum(5, 2).call(hooks.auth('myToken-XYZ'));
console.log(sumTwoResp); // 7

// validate parameters locally without calling the server
const validationResp: ParamsValidationResponse = await routes.utils
    .sayHello({id: '123', name: 'John', surname: 'Doe'})
    .validate();
console.log(validationResp); // {hasErrors: false, totalErrors: 0, errors: []}
Table of Contents