node package manager
Painless code sharing. npm Orgs help your team discover, share, and reuse code. Create a free org »

spust-koa

spust-koa

npm CircleCI

Write your Koa 2.0 backend using JSX and React.

Installation

yarn add spust-koa
 
# or 
 
npm install spust-koa

Usage

Client side react application

import ClientSideRender from 'spust-koa/lib/react/ClientSideRender';
import React from 'react';
import Server from 'spust-koa/lib/Server';
import serve from 'spust-koa';
 
// will start listening automatically
export default serve(
  <Server port={3000}>
    <ClientSideRender />
  </Server>
);

Client side react application with Apollo GraphQL backend

import ClientSideRender from 'spust-koa/lib/react/ClientSideRender';
import GraphQL from 'spust-koa/lib/ApolloGraphQL';
import React from 'react';
import Server from 'spust-koa/lib/Server';
import serve from 'spust-koa';
 
import schema from './yourSchema';
 
// will start listening automatically
export default serve(
  <Server port={3000}>
    <GraphQL schema={schema} />
    <ClientSideRender />
  </Server>
);

Custom backend

import Middleware from 'spust-koa/lib/Middleware';
import Server from 'spust-koa/lib/Server';
import serve from 'spust-koa';
 
// will start listening automatically
export default serve(
  <Server port={3000}>
    <Middleware use={(ctx, { skip }) => {
      if (ctx.url === '/') {
        ctx.status = 200;
        ctx.body = 'Homepage';
 
        skip();
      }
    }} />
    <Middleware use={(ctx) => {
      if (ctx.url === '/a') {
        ctx.status = 200;
        ctx.body = 'a';
      }
    }} />
  </Server>
);

Available components and API

serve(server: <Server />, listenAutomatically?: boolean = true)

helper which extract server instance from your declaration and handles listening

Arguments

  • server: Server element
  • listenAutomatically: optional argument, if you pass false, server won't start listening automatically

Server<{ port: number }>

Root component of your server

Props

  • port: required prop, port on which your server will listen

Middleware<{ use: (context: Koa2Context, controllers: Controllers) => Promise<void> | void }>

Component used to define your middleware functions

Props

  • use: required prop, function accepting context and controllers arguments
    • context: Koa 2 context, see Koa's context documentation
    • controllers: helper methods used to control the flow of middleware functions, consists of:
      • finish: Function
        • interrupts the execution of the current middleware and skips execution of the middleware functions in the current level
        • returns to the parent level, so flow in the parent level can continue
      • nested: () => Promise<void>
        • implicitly calls nested middleware functions (nested middlewares will be called in the scope of the middleware)
        • if you don't use nested() in your middleware function, it will call them automatically after the middleware function is finished (but outside of its scope)
      • skip: Function - interrupts the execution of the current middleware and proceeds to the next middleware in the current level

ApolloGraphQL<{ path: string, methods: string | Array<string>, schema: DocumentNode }>

Create GraphQL server using Apollo's Koa middleware

Props

  • path: string - optional prop
  • methods: string | Array<string> - optional prop
  • schema: DocumentNode: required prop, your GraphQL schema

BodyParser

Parses request's bodies (json, etc)

Cors<{ allowMethods, allowHeaders, credentials, exposeHeaders, keepHeadersOnError, maxAge, origin }>

Add CORS support to your server

Props

See koa cors's documentation

ErrorHandler<{ onError: (e: Error) => void }>

Error handler middleware, can be used multiple times to ensure error handling on different levels of your server

Props

  • onError: (e: Error) => void - required prop used to do something with an error (for example report it somewhere)

Files<{ dir: string, ...}>

Serves static files

Props

GraphiQL<{ path: string, endpointURL: string }>

Creates GraphiQL route

Props

  • path: string - optional prop
  • endpointURL: string - optional prop, path to graphql endpoint

RenderApp<{ render: (ctx: Koa2Context) => Promise<Result> | Result}>

Renders your application

Props

Secure<Props>

Secures your application, see helmet's documentation and hpp's documentation

Props

Session<{ key: string, store: Object, cookie: Object}>

Add support for sessions

Props

react/ClientSideRender<Props>

Creates HTML page for client side React app

Props

  • containerId: string - optiona prop, react app container element id, default app
  • title: string - optional prop, page title
  • lang: string - optional prop, html lang, default en