spust-koa
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 passfalse
, 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 acceptingcontext
andcontrollers
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
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
-
dir
:string
- required prop, absolute path to directory - ..., see Koa static cache's options
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
-
render
: required prop, see documentation-
ctx
:Koa2Context
, see Koa 2.0 context api documentation
-
Secure<Props>
Secures your application, see helmet's documentation and hpp's documentation
Props
-
contentSecurityPolicy?
- optional prop -
dnsPrefetchControl?
- optional prop -
expectCertificateTransparency
- optional prop -
frameguard
- optional prop -
hidePoweredBy
- optional prop -
httpParameterPollution
- optional prop -
httpPublicKeyPinning
- optional prop -
httpStrictTransportSecurity
- optional prop -
ieNoOpen
- optional prop -
noCache
- optional prop -
noSniff
- optional prop -
referrerPolicy
- optional prop -
xssFilter
- optional prop - for more explainations see helmet's documentation and hpp's documentation
Session<{ key: string, store: Object, cookie: Object}>
Add support for sessions
Props
-
store
:Object
- required prop - for whole documentation see koa-session-minimal's documentation
react/ClientSideRender<Props>
Creates HTML page for client side React app
Props
-
containerId: string
- optiona prop, react app container element id, defaultapp
-
title: string
- optional prop, page title -
lang: string
- optional prop, html lang, defaulten