TS-GQL-endpoint | skeleton | TGRstack

Development and Production Ready |⸰| VSCode Extensions

About

Expose all the knobs |⸰| As lean as a racehorse can get |⸰| Fork and keep as an upstream, then create your own endpoints

The skeleton-tg-endpoint is a graphql-endpoint API starterkit/boilerplate. This skeleton demonstrates digesting remote third-party APIs to provide an experiential graphql gateway used by clients (primarily web, but as a developer API too).

1. Configuration is primarily driven by ENV variables (required are set in .env.example).
2. An express server is the foundation of this service.
3. Several express middlewares are applied for a production class setup.
4. Then Apollo Server and GraphiQL (Playground) are attached to the server with their middlewares.

Passport.JS authorization w/ JWT

The preferred way of authorizing a client to pull data is for them to request a JWT from an authorization service, and providing this key for subsequent data requests.

Setting this up is outside the scope of the skeleton. A tutorial will be included here (TODO: write graphql auth enpdoint tutorial).

TGR Packages (npm - @tgrx)

  "dependencies": {},
  "devDependencies": {
    "@tgrx/tslint-config-tgr": "5.0.0", # TGR tslint settings for minimial clutter

Upgrading your Skeleton from an upstream

Github Documentation

Initial Setup

1. First, clone this repo to your local machine
2. Change the remote name git remote rename origin upstream
3. Create a new repository in github/gitlab
4. Add the new remote git remote add origin <your-new-address>

Usage

When updates for the upstream are available, merge them into your skeleton

git pull upstream master
# Handle merge conflicts if necessary
git commit # commit the changes if necessary
git push origin master

Developing a TS-Service

After you've cloned this repo and ran npm i -D, do the following:

in your terminal:

$ nps ss
# Starts the dev server

Commands

* nps                   # Executes all the tooling (watch server + watch linting)
* nps start.server      # Nodemon and webpack builds restart when files change
* nps help              # Displays all available commands
* nps commit            # Creates a commit, don't use `git commit -m ...`
* nps build             # Builds a development version of the service
* nps build.prod        # Builds a production version of the service (w/ some testing - overidable)
* nps lint              # Lint checks the module
* nps test              # Test checks the module

Stack

Docs

• TGRstack.com Wiki
• How to make a TS Module w/ Declarations
• TS-React-App

File Structure

src/
├── __tests__/    - TODO: tests for stack.ts
├── config/       - server configs and vars
├── gql/          - schema, resolvers, mutations for GraphQL
├── middlewares/  - third-party HOC functionality (apollo, loggers, routers)
├── modules/      - first-party modules (co-developed)
    └── some-lib  - pre-cursor to extracting a module
├── service/      - service initialization (express, apollo, storybook)
├── types/        - ts modules, common, interfaces
├── utils/        - useful functions
├── index.ts      - build/service entry point
└── stack.ts      - import service & middlewares

Directories

/
├── .netlify/         - pretty good for rolling builds                      (hidden)
├── .vscode/          - some sane settings but hides lightly used folders   (hidden)
├── build/            - the output of the webpack build process             (hidden)
├── jest/             - Jest setup and mocks                                (hidden)
├── logs/             - Store logs in files (configged by `module/logger`)
├── node_modules/         - the output of `npm i -D`                        (hidden)
├── scripts/          - LOOK IN HERE, all the functionality avail in `nps`
├── src/              - LOOK IN HERE, the server
    └── <DESCRIBED IN-DEPTH ABOVE>
├── webpack/          - Webpack configuration for making builds             (hidden)
├── .babelrc          - transpilation settings mixed w/ tsconfig            (hidden)
├── .env              - server environment's settings (removed by `.gitignore`)
├── .env.development  - suggestions for development env settings
├── .env.example      - a list of required `.env` settings
├── .gitignore        - a list of files that should not be checked into git (hidden)
├── .npmignore        - a list of files that should not be published to npm (hidden)
├── .npmrc            - npm install settings (package-lock.json disabled)   (hidden)
├── .nvmrc            - nvm config that sets the terminals NPM version      (hidden)
├── jest.config.js    - npm install settings (package-lock.json disabled)   (hidden)
├── nodemon.json      - configure nodemon (especially which directories to ignore)  (hidden)
├── package-scripts.js - nps entry point (reroutes to `/scripts/`)          (hidden)
├── package.json      - list of npm packages to be installed
├── README.md         - the most important documentation
├── TODO.md           - checklist of goals for the project
├── tsconfig.jest.json - Jest specific Typescript configuration             (hidden)
├── tsconfig.json     - Typescript settings and module aliasing             (hidden)
└── tslint.json       - Linting settings (**replaced by ESlint 2019Q3**)    (hidden)

Accessing Hidden Files from VSCode

If you are using VSCode to develop this project you will notice a lot of files are hidden by the editor. This is a workspace setting which you can access with ctrl+p ./vscode/settings.json. Any file/folder which is set to true in "files.exclude" is automatically excluded by "search.exclude". So to make the workspace settings file available in the search but hidden in the file explorer (left sidebar) the file must be specified in "search.exclude" and set to false.

This way files are accessible by search but your sidebar isn't cluttered w/ lightly used configs

Features

Features added onto TS-Service

Express

• 🌐 express-server
• 🍞 in dev a browser to the website is opened
• 🚞 Winston unified logger to files and console
• 🔒 Helmet for common security holes
• 🔒 CORS for Cross Origin denial

GraphQL

• 📡 apollo-server-2
• 😋 playground (not graphiql because using JWT instead of sessions)
• ➿ apollo-server w/ subscriptions (websocket)

Build

• 🚦 webpack-graphql-loader for separating gql from ts files

Features from TS-Service

Core

• 🚀 ES2018+ support syntax that is stage-3 or later in the TC39 process.
• 🎛 Preconfigured to support development and optimized production builds
• 🎶 typescript incremental returns reducing development bugs

Utils

• 🎮 nps node-package-scripts removes the limitation of package.json enabling JS & //comments . Modify /package-scripts.js and use nps <command> instead of npm run <command>.
• 🙌 commitizen to help us generate beautifully formatted and consistent commit messages.
• 😹 cz-emoji is a plugin for commitizen that adds emoji to the commit template.
• 🏆 standard-version is a replacement for npm version with automatic CHANGELOG generation
• ✅ commitlint validates commit messages to follow commitizen patterns

Style

• 🚦 tslint configured for strict, consistent, code style
• 🚦 eslint replacing TSLint in 2019Q3
• 🚦 ts-prettier for some of that code-consistancy that's missing from tslint
• 🚦 SonarTS Static code analyzer detects bugs and suspicious patterns

Tests

• 🎭 jest as the test framework.
• 🎭 ts-jest configured to test TS files, uses tsconfig.jest.json, and skip babel.
• 🎭 enzyme makes it easier to assert, manipulate, and traverse components.

Build (w/ Webpack)

• 📦 All source is bundled using Webpack v4
• 🌟 webpack for dev, prod, common
• 🚦 ts-loader for compiling typescript
• 💦 babel-loader for additional polyfills (browser support)
• 😎 HappyPack
• 🤖 Auto generated Vendor DLL for smooth development experiences
• 🍃 Tree-shaking