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.
- Download the repository
- Remove the existing git repository (by deleting the
.gitfolder) and initialize a new one for your project - Edit relevant fields in
package.json - Develop away with
npm start - Build app for production with
npm run build
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 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"
]
}
}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.
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.
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"
}
]
}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
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 */
})
)
);
};
}
}If you want to develop React applications, I recommend using Next.js instead.
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).
TBD - MobX recommended since it's written in TypeScript & is great
TBD - Jest with ts-jest?