Skip to content

My personal lean template for building projects with TypeScript.

Notifications You must be signed in to change notification settings

Daiz/typescript-webapp-template

Repository files navigation

TypeScript Starter Template

This is my personal minimal template for getting quickly started with building front-end libraries with TypeScript.

It's intended to be used with Visual Studio Code in order to get automatic formatting with Prettier on saving. You can configure other editors to do this too, but the repository only includes configuration files for VS Code, since it's what I use myself.

How to use

  1. Download the repository
  2. Remove the existing git repository (by deleting the .git folder) and initialize a new one for your project
  3. Edit relevant fields in package.json
  4. Develop away with npm start
  5. Build app for production with npm run build

What's included

Webpack bundles the project, naturally. May get replaced with Parcel in the future, but for the time being Webpack enables more useful features.

A live reloading development server is also a must, which is why we also have Webpack Serve. You can also use it to preview your project over local WiFi (useful for testing with eg. real mobile devices). To do this, run npm set typescript-starter-template:host 192.168.X.X (replace typescript-starter-template with the value of name in your package.json) with the IP pointing to your local WiFi network IP address. Make sure to restart the dev server when changing this. Now you should be able to preview your app from other devices by accessing it via the defined IP.

Web Worker support

Web Workers take a considerable amount of setup to make them function properly with both Webpack and TypeScript, not to mention making all the communication with workers typed. Which is why the template is configured for this use case, along with example code on how to make typed web workers.

Just focus on the coding and let Prettier take care of the formatting for you. Make sure to use an editor that can run Prettier on file save. VS Code will do it by default with the configuration files in this repository after you install the Prettier extension (which is automatically recommended by VS Code once you open the project)

A minimal TSLint configuration with typescript-tslint-plugin (so you don't need a TSLint plugin in your editor - if you have one, you should disable it) is included that flags the usage of == and != over === and !== as errors (triple-equals rule), except for comparison against null. If you want a wider set of TSLint rules to use, consider tslint-config-standard. To use it, simply change your tslint.json to the following:

{
  /* your personal tslint config */
  "extends": ["tslint-config-standard", "tslint-config-prettier"]
  /* make sure tslint-config-prettier comes last as it ensures lint rule compatibility with Prettier */
}

If you or someone else you work with isn't using VS Code, you can also configure linting to be enforced on pre-commit level. To do this, you should first npm install lint-staged husky, then add the following to your package.json:

{
  "scripts": {
    "precommit": "lint-staged",
    "lint": "tslint --type-check --project tsconfig.json \"src/**/*.ts*\""
  },
  "lint-staged": {
    "*.{ts,tsx}": [
      "tslint --fix",
      "prettier --parser typescript --write",
      "git add"
    ]
  }
}

What's not included

CSS-in-JS

If you want a CSS-in-JS solution, I recommend TypeStyle. Works great with TypeScript! To get it and its helper libraries, just run npm install typestyle csx csstips and you'll be up and running in no time.

Automatic vendor bundling support

AutoDllPlugin is a wonderful tool for improving build times and separating dependencies into its own vendor bundle. Recommended if you include heavier production dependencies that will rarely update. Webpack 5 should eventually come with similar caching out of the box.

External CSS loaders

If you want to use something like eg. Sass, you'll want to npm install -D node-sass sass-loader css-loader style-loader and add the following to webpack.config.js into the module rules array:

{
  test: /\.s?[ca]ss$/,
  use: [{
      loader: "style-loader"
    },
    {
      loader: "css-loader"
    },
    {
      loader: "sass-loader"
    }
  ]
}

File Embedding

If you want to embed files directly into your bundle as Data URIs, you can npm install -D url-loader and add the following to webpack.config.js into the module rules array:

{
  test: /\.(png|jpg|gif|woff|woff2|eot|ttf|svg)$/, // applied to images & fonts
  use: [{
    loader: "url-loader",
    options: {
      limit: 100000 // maximum size in bytes for an asset to get inlined
    }
  }]
}

By using external CSS you'll most likely want to remove TypeStyle from the project as well with npm unistall typestyle

History API fallback for development server

This allows you to redirect requests to non-existent resources back to your index file. Primarily useful for webapps that work with "bare" URLs ([host]/webapp/route/index) instead of eg. hashbangs ([host]/#!/webapp/route/index). To add this functionality, first run npm install -D koa-connect connect-history-api-fallback and then add the following into your webpack.config.js:

// At the top of the file
const convert = require("koa-connect");
const history = require("connect-history-api-fallback");
// in the `serve` section of the config:
{
  serve: {
    add: (app, middleware, options) => {
      // For available options, consult the following:
      // https://github.com/bripkens/connect-history-api-fallback#options
      app.use(
        convert(
          history({
            /* options */
          })
        )
      );
    };
  }
}

React

If you want to develop React applications, I recommend using Next.js instead.

Routing

Currently the template does not include anything for routing, but I will probably make an opinionated choice at some point after I find a router that's satisfying to work with in TypeScript and fulfills my personal needs. This is primarily intended for React, and any included-by-default router can and should obviously be removed if you decide to go with a framework/library with routing built in (or if you simply don't need routing).

State Management

TBD - MobX recommended since it's written in TypeScript & is great

Testing

TBD - Jest with ts-jest?

License

Creative Commons Zero (CC0) 1.0 Universal