# koa-spark

> Koa application boilerplate-less

Latest version **0.4.3** (published 2022-02-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install koa-spark
pnpm add koa-spark
yarn add koa-spark
bun add koa-spark
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.4.3 |
| Published | 2022-02-21 |
| First published | 2020-06-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 16 |
| Unpacked size | 463.3 KB |
| Known vulnerabilities | 0 (+2 in 2 direct dependencies) |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Luca Faggianelli |
| Maintainers | lfaggia, lucafaggianelli |

## Links

- npm: https://www.npmjs.com/package/koa-spark
- Repository: https://github.com/lucafaggianelli/koa-spark
- npm.io page: https://npm.io/package/koa-spark

## Dependencies (16)

- [koa](https://npm.io/package/koa.md) ^2.12.0
- [pino](https://npm.io/package/pino.md) ^7.1.0
- [dotenv](https://npm.io/package/dotenv.md) ^10.0.0
- [js-yaml](https://npm.io/package/js-yaml.md) ^4.1.0
- [koa-body](https://npm.io/package/koa-body.md) ^4.1.3
- [@koa/cors](https://npm.io/package/@koa/cors.md) ^3.1.0
- [deepmerge](https://npm.io/package/deepmerge.md) ^4.2.2
- [koa-helmet](https://npm.io/package/koa-helmet.md) ^6.1.0
- [koa-logger](https://npm.io/package/koa-logger.md) ^3.2.1
- [koa-static](https://npm.io/package/koa-static.md) ^5.0.0
- [@koa/router](https://npm.io/package/@koa/router.md) ^10.1.1
- [koa-session](https://npm.io/package/koa-session.md) ^6.2.0
- [koa-joi-router](https://npm.io/package/koa-joi-router.md) ^8.0.0
- [reflect-metadata](https://npm.io/package/reflect-metadata.md) ^0.1.13
- [joi-to-json-schema](https://npm.io/package/joi-to-json-schema.md) ^5.1.0
- [typeorm-express-query-builder](https://npm.io/package/typeorm-express-query-builder.md) ^1.5.1

## Recent versions

- 0.4.3 (latest) — 2022-02-21
- 0.4.2 — 2022-02-21
- 0.4.1 — 2022-02-07
- 0.4.0 — 2022-01-28
- 0.3.0 — 2021-11-04
- 0.2.2 — 2020-10-29
- 0.2.1 — 2020-07-23
- 0.2.0 — 2020-07-16
- 0.1.0 — 2020-06-09

## README

# KoaSpark - Koa application boilerplate-less

Build Koa applications in a spark.

KoaSpark is a *boilerplate-as-a-library* for creating Koa apps, it includes out-of-the-box many koa plugins that
you normally need for an app like `koa-body`, `koa-cors` and `koa-router`, plus many other useful features
like the automatic generation of *OpenAPI* definitions.

All of this is typically found in *templates* and *boilerplates* via cloning a base git repo and then editing it or
via a CLI that generates code, this approach works but keep your app updated when a new version of the template is released
is a nightmare.

KoaSpark has a differnet approach, it doesn't generate any code, it's just an `import`able library that provides an alternative
to `const app = new Koa()`: `const app = createApp(config, options)` and you have a KoaApp ready to use.

## Get Started

```sh
npm install koa-spark
# or
yarn add koa-spark
```

Then create the app:

```ts
import { createApp } from 'koa-spark'

const app = createApp()

if (require.main === module) {
  app.startServer()
}
```

## Configuration

In Koa Spark, there are 2 levels of configuration, at the app level `AppConfig` and at the framework level `SparkOptions`.
They are both passed to the `createApp(AppConfig, SparkOptions)` function.

### App Configuration

The app configuration holds environment-specific configurations, like secrets, connection info, etc. that should be changed
by the final user if you redistribute the app, or changed when you deploy in production.

The AppConfig can be configured via environmental variables and/or `.env` files, Koa Spark will automatically initialize the `AppConfig`
properties decorated with `@Field()` with the corresponding environment variable. Note that AppConfig properties are written in `camelCase`
but env variables are written in `UPPER_SNAKE_CASE`.

```ts
// config.ts
import { AppConfig, Field } from 'koa-spark'

class MyAppConfig extends AppConfig {
  @Field({ default: 'test@localhost' }) // env: FROM_ADDRESS
  fromAddress!: string

  @Field() // env: GCLOUD_STORAGE_BUCKET
  gcloudStorageBucket!: string

  @Field({ default: 'mongodb://localhost/thedb' })
  mongodbConnectionUri!: string

  @Field()
  sendgridApiKey!: string
}

export default new MyAppConfig()
```

And its relative `.env` file:

```sh
# .env
FROM_ADDRESS=luca@mail.com
GCLOUD_STORAGE_BUCKET=my_bucket_production
```

You can have multiple `.env` files, one per each environment, named `.env.<NODE_ENV>`.
Koa Spark will try to load the environment-specific file and fallback to the generic one,
for example in production will try to load `.env.production` and if it's missing will load `.env`.

### Framework Options

The framework options `SparkOptions` are used to configure Koa Spark itself, are more *inner-configs* than
`AppConfig`, for example they include configurations for *CORS*, *helmet*, etc.

As for their nature, framework options are not configurable via env variables, but only via code:

```ts
const app = createApp(
  config,
  {
    body: {
      multipart: true
    }
  }
)
```

---
_Source: https://npm.io/package/koa-spark · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._