Example micro description.
Explore API docs »
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:
- Typescript (Develop a strongly typed application)
- Tests using mocha & chai (Write unit tests for different components)
- API Tests (Coming soon: Test your api)
- API Documentation using SwaggerUI (Access the SwaggerUI webinterface to view & try your api)
- API Validation (Ensure all requests and responses adhere to an OpenAPI specification)
- API Versioning (Run multiple endpoint versions at once to retain backwards compatability)
- Different environments (Change the behaviour of your api in different environments -> by default:
sandbox
&production
) - CI/CD Pieline using github actions
- Configurable includes (e.g. static files)
- Easy developer experience
- Easily configure your micro and environments from
deta.json
file - Easily build & deploy changes using npm scripts
- Start a local dev server
- Easily configure your micro and environments from
- 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 intobuild/
) - Run
npm run dev:sandbox
to try out your micro locally - Run
npm run deploy
to deploy your environments to the cloud
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
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 & Explorerhttps://xxx/v1/spec.yaml
: The spec.yaml filehttps://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.
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
}
]
}
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 fromsrc/
to the build output directory.
Builds the specified environment and runs the
devServer.js
file inside that environments directory.
Runs tests (must not fail!), builds the specified environment (empty for all), runs detaSetup and deploy tasks. If
confirmDeploy
istrue
indeta.json
file, The user is prompted to confirm the deploy action.
Runs detaSetup task which creates new micros or clones existing ones from the configured project.
Installs project dependencies for development, builds the project and calls npm run detaSetup.
Only checks or changes (writes) to all files inside
src/
&test/
enforcing the.prettierrc.json
specification.
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.
- Add CI/CD Env option which skipps prompt
- Cache node-modules