{"id":13602759,"url":"https://github.com/kriasoft/node-starter-kit","last_synced_at":"2025-04-11T09:30:53.127Z","repository":{"id":44341525,"uuid":"52716305","full_name":"kriasoft/node-starter-kit","owner":"kriasoft","description":"Node.js / GraphQL project template pre-configured with TypeScript, PostgreSQL, login flow, transactional emails, unit tests, CI/CD workflow.","archived":false,"fork":false,"pushed_at":"2021-07-14T12:59:56.000Z","size":2991,"stargazers_count":165,"open_issues_count":0,"forks_count":28,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-10-30T00:55:25.983Z","etag":null,"topics":["babel","boilerplate","cloud-functions","database","graphql","javascript","knex","knexjs","node","nodejs","postgres","postgresql","seed","sql","starter","starter-kit","template","typescript","webapp","website"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kriasoft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"patreon":"koistya"}},"created_at":"2016-02-28T10:41:57.000Z","updated_at":"2024-10-29T02:08:12.000Z","dependencies_parsed_at":"2022-07-16T02:46:14.540Z","dependency_job_id":null,"html_url":"https://github.com/kriasoft/node-starter-kit","commit_stats":null,"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kriasoft%2Fnode-starter-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kriasoft%2Fnode-starter-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kriasoft%2Fnode-starter-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kriasoft%2Fnode-starter-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kriasoft","download_url":"https://codeload.github.com/kriasoft/node-starter-kit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248368201,"owners_count":21092316,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["babel","boilerplate","cloud-functions","database","graphql","javascript","knex","knexjs","node","nodejs","postgres","postgresql","seed","sql","starter","starter-kit","template","typescript","webapp","website"],"created_at":"2024-08-01T18:01:37.202Z","updated_at":"2025-04-11T09:30:52.676Z","avatar_url":"https://github.com/kriasoft.png","language":"TypeScript","readme":"# Node.js API Starter Kit\n\n\u003ca href=\"http://www.typescriptlang.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg?style=flat-square\" height=\"20\"\u003e\u003c/a\u003e\n\u003ca href=\"http://patreon.com/koistya\"\u003e\u003cimg src=\"https://img.shields.io/badge/dynamic/json?color=%23ff424d\u0026label=Patreon\u0026style=flat-square\u0026query=data.attributes.patron_count\u0026suffix=%20patrons\u0026url=https%3A%2F%2Fwww.patreon.com%2Fapi%2Fcampaigns%2F233228\" height=\"20\"\u003e\u003c/a\u003e\n\u003ca href=\"https://discord.gg/GrqQaSnvmr\"\u003e\u003cimg src=\"https://img.shields.io/discord/643523529131950086?label=Chat\u0026style=flat-square\" height=\"20\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/kriasoft/node-starter-kit/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/kriasoft/node-starter-kit.svg?style=social\u0026label=Star\u0026maxAge=3600\" height=\"20\"\u003e\u003c/a\u003e\n\u003ca href=\"https://twitter.com/koistya\"\u003e\u003cimg src=\"https://img.shields.io/twitter/follow/koistya.svg?style=social\u0026label=Follow\u0026maxAge=3600\" height=\"20\"\u003e\u003c/a\u003e\n\nNode.js API Starter Kit is a project template for building Node.js backend applications\noptimized for serverless infrastructure such as [Google Cloud Functions](https://cloud.google.com/functions),\n[AWS Lambda](https://aws.amazon.com/lambda/), [Azure Functions](https://azure.microsoft.com/services/functions/), etc.\nUse it as an API server for your front-end app.\n\n## Features\n\n- Database first design; auto-generated strongly typed data models (TypeScript)\n- Authentication and authorization using OAuth 2.0 providers (Google, Facebook, GitHub, etc.)\n- Stateless sessions implemented with JWT tokens and a session cookie (compatible with SSR)\n- GraphQL API example, implemented using the code-first development approach\n- Database schema migration, seeds, and REPL shell tooling\n- Transactional emails using Handlebars templates and instant email previews\n- Structured logs and error reporting to Google StackDriver\n- Pre-configured unit testing tooling powered by [Jest](https://jestjs.io/) and [Supertest](https://github.com/visionmedia/supertest)\n- Application bundling with Rollup as an optimization technique for serverless deployments\n- Rebuilds and restarts the app on changes when running locally\n- Pre-configured for `local`, `dev`, `test`, and `prod` environments\n- The ongoing design and development is supported by these wonderful companies:\n\n\u003ca href=\"https://reactstarter.com/s/1\"\u003e\u003cimg src=\"https://reactstarter.com/s/1.png\" height=\"60\" /\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u003ca href=\"https://reactstarter.com/s/2\"\u003e\u003cimg src=\"https://reactstarter.com/s/2.png\" height=\"60\" /\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u003ca href=\"https://reactstarter.com/s/3\"\u003e\u003cimg src=\"https://reactstarter.com/s/3.png\" height=\"60\" /\u003e\u003c/a\u003e\n\n![](https://files.tarkus.me/graphql-api.png)\n\n---\n\nThis project was bootstrapped with [Node.js API Starter Kit](https://github.com/kriasoft/node-starter-kit).\nBe sure to join our [Discord channel](https://discord.com/invite/GrqQaSnvmr) for assistance.\n\n## Tech Stack\n\n- [Node.js](https://nodejs.org/) v14, [Yarn](https://yarnpkg.com/) package manager,\n  [TypeScript](https://www.typescriptlang.org/), [Babel](https://babeljs.io/),\n  [Rollup](https://rollupjs.org/), [ESLint](https://eslint.org/),\n  [Prettier](https://prettier.io/), [Jest](https://jestjs.io/)\n- [PostgreSQL](https://www.postgresql.org/), [GraphQL.js](https://github.com/graphql/graphql-js),\n  [Knex](https://knesjs.org/), [Express](https://expressjs.com/),\n  [Nodemailer](https://nodemailer.com/),[Email Templates](https://email-templates.js.org/),\n  [Handlebars](https://handlebarsjs.com/), [Simple OAuth2](https://github.com/lelylan/simple-oauth2)\n\n## Directory Structure\n\n`├──`[`.build`](.build) — Compiled and bundled output (per Cloud Function)\u003cbr\u003e\n`├──`[`.vscode`](.vscode) — VSCode settings including code snippets, recommended extensions etc.\u003cbr\u003e\n`├──`[`api`](./api) — Cloud Function for handling API requests using [GraphQL.js](https://github.com/graphql/graphql-js)\u003cbr\u003e\n`├──`[`auth`](./auth) — Authentication and session middleware\u003cbr\u003e\n`├──`[`core`](./core) — Common application modules (email, logging, etc.)\u003cbr\u003e\n`├──`[`db`](./db) — Database client for PostgreSQL using [Knex](https://knexjs.org/)\u003cbr\u003e\n`├──`[`emails`](./emails) — Email templates for transactional emails using [Handlebars](https://handlebarsjs.com/)\u003cbr\u003e\n`├──`[`env`](./env) — Environment variables for `local`, `dev`, `test`, and `prod`\u003cbr\u003e\n`├──`[`migrations`](./migrations) — database schema migrations ([Cloud SQL](https://cloud.google.com/sql), [Knex](https://knexjs.org/))\u003cbr\u003e\n`├──`[`scripts`](./scripts) — Deployment scripts, REPL shell, etc.\u003cbr\u003e\n`├──`[`test`](./test) — Unit tests and benchmarks\u003cbr\u003e\n`├──`[`views`](./views) — HTML templates using [Handlebars](https://handlebarsjs.com/)\u003cbr\u003e\n`└── ...` — add more cloud functions such as `worker`, `notifications`, etc.\n\n## Requirements\n\n- [Node.js](https://nodejs.org/) v14, [Yarn](https://yarnpkg.com/) package manager\n- Local or remote instance of [PostgreSQL](https://www.postgresql.org/) (see [Postgres.app](https://postgresapp.com/), [Google Cloud SQL](https://cloud.google.com/sql))\n- [VS Code](https://code.visualstudio.com/) editor with [recommended extensions](.vscode/extensions.json)\n\n## Getting Started\n\n- Clone the repo — `git clone -o seed https://github.com/kriasoft/node-starter-kit.git`.\n- Update environment variables for `local`, `dev`, `test`, and `prod` environments ([`./env`](./env)).\n- Install project dependencies — `yarn install`\n- Bootstrap PostgreSQL database — `yarn db:create`\n- Finally, launch the app — `yarn start`, it will become available at [http://localhost:8080](http://localhost:8080/).\n\nUse `APP_ENV` environment variable to execute scripts for different environments, for example:\n\n```\n$ APP_ENV=test yarn db:migrate\n$ APP_ENV=test yarn start\n```\n\n![](https://files.tarkus.me/node-starter-kit-start.svg)\n\n**IMPORTANT**: Ensure that VSCode is using the workspace versions of TypeScript and ESLint.\n\n![](https://files.tarkus.me/typescript-workspace.png)\n\n## Scripts\n\n- `yarn start` — Launches the app in development mode on [`http://localhost:8080`](http://localhost:8080/)\n- `yarn build` — Compiles and bundles the app for deployment\n- `yarn lint` — Validate code using ESLint\n- `yarn tsc` — Validate code using TypeScript compiler\n- `yarn test` — Run unit tests with Jest, Supertest\n- `yarn repl` — Connect to the database using Knex REPL shell\n- `yarn psql` — Connect to the database using PostgreSQL CLI\n- `yarn db:create` — Create a new database\n- `yarn db:version` — Check the current version of the database\n- `yarn db:migrate` — Migrate database schema to the latest version\n- `yarn db:rollback` — Rollback the latest migration\n- `yarn db:seed` — Seed database with sample / reference data\n- `yarn db:reset` — Re-apply the latest DB schema migration file\n- `yarn update-types` — Generate strongly typed data models from database schema\n\nOptionally set `APP_ENV` to `local` (default), `dev`, `test`, or `prod` before running these scripts.\n\n![](https://files.tarkus.me/node-starter-kit-db.svg)\n\n## How to Configure 0Auth 2.0 Login Flow\n\nFor each 3rd party identity provider that needs to be enabled for your app, you\nwill need to obtain application credentials, often called client ID/secret.\n\n### Google\n\n- Go to [Google Cloud Console](https://console.cloud.google.com/)\n- [Create a new GCP project](https://console.cloud.google.com/projectcreate)\n- [Configure OAuth concent screen](https://console.cloud.google.com/apis/credentials/consent)\n- [Create OAuth 2.0 client](https://console.cloud.google.com/apis/credentials/oauthclient)\n  with `http://localhost/auth/google/return` as the callback URL\n- Update `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` environment variables\n  found in [`./env/.env.*`](./env/) for each environment that you need.\n\nFrom there on, visiting [`http://localhost:8080/auth/google`](http://localhost:8080/auth/google)\n(or, opening it in a popup window) would initiate login flow via Google.\n\n### Facebook\n\n- Go to [Facebook Developer](https://developers.facebook.com/apps/) website\n- Create a new Facebook App, enable Facebook Login for this app\n- Close Quickstart dialog and go straight to the app settings\n- Add `http://localhost/auth/facebook/return` as the callback URL for the login flow\n- Copy and paste the newly created Facebook App ID and secret to\n  `FACEBOOK_APP_ID`, `FACEBOOK_APP_SECRET` variables found in [`env/.env.*`](./env/)\n  files for each environment that you need.\n\nFrom there on, visiting [`http://localhost:8080/auth/facebook`](http://localhost:8080/auth/facebook)\n(or, opening it in a popup window) would initiate login flow via Facebook.\n\n## How to Deploy\n\nThe deployment script (`yarn deploy`) relies on Google Cloud CLI (`gcloud`) tool\nthat you can download from [here](https://cloud.google.com/sdk/docs/install). For\nCI/CD workflows you may need a Docker image like [this one](https://github.com/marketplace/actions/google-cloud-platform-gcp-cli-gcloud).\n\n`gcloud auth login` — Authorize Google Cloud SDK (CLI) tool to use your Google account.\n\n[Create](https://console.cloud.google.com/projectcreate) a new GCP project for\nyour app with IDs such as `example` for production, and `example-test` for test\n/ QA environments. Ensure that Cloud Build API and Cloud Functions API are\nenabled in your GCP project's settings [here](https://console.cloud.google.com/apis/library).\n\nCreate a Cloud SQL database instance [here](https://console.cloud.google.com/sql)\nin the same region where your app needs to be deployed. Using a micro instance\nof Cloud SQL with 0.6 GB RAM should be OK for testing and low traffic websites.\n\nEnsure that `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_REGION`, `PGDATABASE`, `PGUSER`\nand the other environment variables are correctly set for the target deployment\nenvironment (e.g. [`/env/.env`](./env/.env) + [`/env/.env.prod`](./env/.env.prod)\nfor production).\n\nFinally, compile and deploy the app by running:\n\n- `yarn build` — Compiles the app into the `.build` folder\n- `APP_ENV=\u003cenv\u003e yarn db:migrate` — Migrates database (schema) to the latest version\n- `APP_ENV=\u003cenv\u003e yarn deploy` — Deploys the app to Google Cloud Functions (GCF)\n\nWhere `\u003cenv\u003e` is the target environment, e.g. `APP_ENV=prod yarn deploy`.\n\n## How to Update\n\n- `yarn set version latest` — Bump Yarn to the latest version\n- `yarn upgrade-interactive` — Update Node.js modules (dependencies)\n- `yarn pnpify --sdk vscode` — Update TypeScript, ESLint, and Prettier settings in VSCode\n\n## Backers\n\n\u003ca href=\"https://reactstarter.com/b/1\"\u003e\u003cimg src=\"https://reactstarter.com/b/1.png\" height=\"60\" /\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u003ca href=\"https://reactstarter.com/b/2\"\u003e\u003cimg src=\"https://reactstarter.com/b/2.png\" height=\"60\" /\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u003ca href=\"https://reactstarter.com/b/3\"\u003e\u003cimg src=\"https://reactstarter.com/b/3.png\" height=\"60\" /\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u003ca href=\"https://reactstarter.com/b/4\"\u003e\u003cimg src=\"https://reactstarter.com/b/4.png\" height=\"60\" /\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u003ca href=\"https://reactstarter.com/b/5\"\u003e\u003cimg src=\"https://reactstarter.com/b/5.png\" height=\"60\" /\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u003ca href=\"https://reactstarter.com/b/6\"\u003e\u003cimg src=\"https://reactstarter.com/b/6.png\" height=\"60\" /\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u003ca href=\"https://reactstarter.com/b/7\"\u003e\u003cimg src=\"https://reactstarter.com/b/7.png\" height=\"60\" /\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u003ca href=\"https://reactstarter.com/b/8\"\u003e\u003cimg src=\"https://reactstarter.com/b/8.png\" height=\"60\" /\u003e\u003c/a\u003e\n\n## Related Projects\n\n- [GraphQL API Starter Kit](https://github.com/kriasoft/graphql-starter) — monorepo template, pre-configured with TypeScript, GraphQL, React, and Relay.\n- [React Starter Kit](https://github.com/kriasoft/react-starter-kit) — project template, pre-configured with Webpack and React\n\n## How to Contribute\n\nAnyone and everyone is welcome to [contribute](.github/CONTRIBUTING.md). Start\nby checking out the list of [open issues](https://github.com/kriasoft/node-starter-kit/issues)\nmarked [help wanted](https://github.com/kriasoft/node-starter-kit/issues?q=label:\"help+wanted\").\nHowever, if you decide to get involved, please take a moment to review the\n[guidelines](.github/CONTRIBUTING.md).\n\n## License\n\nCopyright © 2016-present Kriasoft. This source code is licensed under the MIT license found in the\n[LICENSE](https://github.com/kriasoft/node-starter-kit/blob/main/LICENSE) file.\n\n---\n\n\u003csup\u003eMade with ♥ by Konstantin Tarkus ([@koistya](https://twitter.com/koistya), [blog](https://medium.com/@koistya))\nand [contributors](https://github.com/kriasoft/node-starter-kit/graphs/contributors).\u003c/sup\u003e\n","funding_links":["https://patreon.com/koistya","http://patreon.com/koistya","https://img.shields.io/badge/dynamic/json?color=%23ff424d\u0026label=Patreon\u0026style=flat-square\u0026query=data.attributes.patron_count\u0026suffix=%20patrons\u0026url=https%3A%2F%2Fwww.patreon.com%2Fapi%2Fcampaigns%2F233228"],"categories":["Related Projects","boilerplate"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkriasoft%2Fnode-starter-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkriasoft%2Fnode-starter-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkriasoft%2Fnode-starter-kit/lists"}