deta.sh-versioned-micro-ts-tests-swagger-validation: A JavaScript repository from MaximilianHeidenreich

Deta.sh micro template

Example micro description.
Explore API docs »

Table of Contents
Abstract
Installation
Project structure
Usage
TODO

Abstract

Thsi repo is an opinionated template for building strong Deta.sh micros. It provides a project structure & dev tools which can be used to quickly develop and deploy express applications. Of course, you can just use the Deta CLI and run all the different commands by yourself, but in case you want a streamlined experience (especially with typescript & different environments), this template might be for you.

It is mainly intendet for serving API's and provides the following featues:

Installation

Install Deta CLI & Authenitcate
Clone this repository
Modify deta.json to configure the deployment
Run npm run setup (This will install dependencies and create micros / clone existing ones into build/)
Run npm run dev:sandbox to try out your micro locally
Run npm run deploy to deploy your environments to the cloud

Project structure

Files with the ? suffix are not required!

This example describes a layout for 2 configured environments: sandbox & production

build/
    sandbox/                - Build output for production environment
    production/             - Build output for production environment
src/                        - All source files of the application
    lib/                    - Utility files (e.g. math, token generation, authentication...)
        routes/
            v1/             - Dir containing router & all route files for v1 specification
                router.ts   - Defines express routes from route files
                index.ts    - Example route file for "/" (Will get mapped to http://xxx/v1/)
                spec.yaml?  - OpenAPI specification for v1 routes
            v2/             - Dir containing router & all route files for v2 specification
                ...
        increment.ts        - Example math function
    devServer.js            - Local dev server
    index.js                - Global (express) configuration
test/                       - Dir containing all tests
    increment.spec.ts       - Example test for increment file
.detaignore                 - Lists files which won't be uploaded to the micro (paths relative to environment build directory)
.production.env             - Environment values for production environment
.sandbox.env                - Environment values for sandbox environment
deta.json                   - Deployment configuration

Usage

Acessing the / root endpoint will give you a json response containing the available api version endpoints like:

// TODO: impl / fix

{
	"v1": "https://detaURL/v1"
}

After installing & setup, you can create your express API routes as usual. If you create a spec.yaml OpenAPI file inside a routes/vX directory, the project automatically adds request & response validation for enpoints which are documented inside spec.yaml and the following endpoints:

https://xxx/v1/docs: SwaggerUI API Docs & Explorer
https://xxx/v1/spec.yaml: The spec.yaml file
https://xxx/v1/spec.json: A transpiled spec.json file

If you want to create a new API version, just duplicate the previous vX directory and make your changes. The new route wil automatically be mounted as long as there is a valid router.ts (router.js after build) file inside the vX directory.

While developing you can either run npm run dev to test your application locally or npm run deploy to build and deploy your latest changes.

deta.json configuration

The deta.json file contains the base configuration for the environment micros and the environments itself.

{
	"micro_name": "exampleAPI", // The name (Will be suffixed with the environment e.g. example-api-sandbox)
	"deta_project": "MicroTSTemplate", // The project in which the micros should exist
	"environments": [
		// Each environment = 1 micro
		{
			"name": "sandbox",
			"auth": false, // Whether to enable/disable api authentication using a project key
			"confirmDeploy": false // Whether to require confirmation when deploying
		},
		{
			"name": "production",
			"auth": false,
			"confirmDeploy": true
		}
	]
}

NPM Scripts

Core

npm run test

Runs all tests inside test/ using mocha and chai.

npm run build:[environment]

Builds all environments or the specified one. Build includes preparing by cleaning the build folders, typescript compilation, transpilation of spec.yam files to spec.json files and copying all necessary project files from src/ to the build output directory.

npm run dev:

Builds the specified environment and runs the devServer.js file inside that environments directory.

npm run deploy:[environment]

Runs tests (must not fail!), builds the specified environment (empty for all), runs detaSetup and deploy tasks. If confirmDeploy is true in deta.json file, The user is prompted to confirm the deploy action.

Utility

npm run detaSetup

Runs detaSetup task which creates new micros or clones existing ones from the configured project.

npm run setup

Installs project dependencies for development, builds the project and calls npm run detaSetup.

npm run format:<check/write>

Only checks or changes (writes) to all files inside src/ & test/ enforcing the .prettierrc.json specification.

Gulp tasks

gulp detaSetup                      - Setups up deta micros (creating / cloning existing) inside environment folders.
gulp build [--env=<environment>]    - Builds all environments or the one specified.
gulp deploy [--env=<environment>]   - Deploys all environments or the one specified.

TODO

Add CI/CD Env option which skipps prompt
Cache node-modules

MaximilianHeidenreich/deta.sh-versioned-micro-ts-tests-swagger-validation