DEV Community

Andreas Augustin
Andreas Augustin

Posted on • Updated on • Originally published at andreasaugustin.github.io

Start a new typescript project with gts and esbuild

#esbuild #typescript #gts #collaboration

Abstract

When starting a new typescript project you need to configure lots of things

  • npm project settings
  • typescript transpiler settings
  • folder structure
  • style checker and formatter
  • bundler

To minize the effort gts is a nice tool to help you setting up the project.
Our of deployment/devliver purposes we also want to bundle the code to create nice and small artifacts.
For those purposes we use esbuild.
The whole example can be found here

Prerequisites

For starting this tutorial you need to have nodejs and npm (also npx) installed on your machine.
Some basic knowledge about nodejs, npm and npx is helpful.

Create the project

Please keep in mind that some of the outputs can vary on your system related to the used versions.

So lets start some actions.
First we want to create the npm project.
Therefore please cd into a nice directory of your choice.

Now lets create the project directory and the npm typescript project with the help of gts.

Remark We add the -y flag to accept the default settings. If you want to adjust those, just do not add the flag.

mkdir ts_gts_esbuild
cd ts_gts_esbuild
npx gts init -y
Enter fullscreen mode Exit fullscreen mode

Analyse

Now lets see what we got.

$ tree -a -L 1
.
├── .eslintignore
├── .eslintrc.json
├── node_modules
├── package.json
├── package-lock.json
├── .prettierrc.js
├── src
└── tsconfig.json

2 directories, 6 files
Enter fullscreen mode Exit fullscreen mode

Because we do not want to add build artifacts and dependent libs to our git database we add them to .gitignore

Remark The build/ folder is used per default for the typescript build artefacts.

echo node_modules/ >> .gitignore
echo build/ >> .gitignore
Enter fullscreen mode Exit fullscreen mode

We can see that we received some default settings

  • npm project settings
  • typescript transpiler settings
  • folder structure
  • style checker and formatter

NPM project settings 

$ cat package.json
{
  "name": "",
  "version": "0.0.0",
  "description": "",
  "main": "build/src/index.js",
  "types": "build/src/index.d.ts",
  "files": [
    "build/src"
  ],
  "license": "Apache-2.0",
  "keywords": [],
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "lint": "gts lint",
    "clean": "gts clean",
    "compile": "tsc",
    "fix": "gts fix",
    "prepare": "npm run compile",
    "pretest": "npm run compile",
    "posttest": "npm run lint"
  },
  "devDependencies": {
    "gts": "^3.1.0",
    "typescript": "^4.0.3",
    "@types/node": "^14.11.2"
  }
}
Enter fullscreen mode Exit fullscreen mode

As you can see some devDependencies have been installed. Also we got some preparations for delivering a npm package.
Furthermore we got some npm scripts.

Typescript transpiler settings 

npm run compile
Enter fullscreen mode Exit fullscreen mode

This will compile the typescript sources defined in tsconfig.json file and put the built aretefacts into the outDir folder defined in tsconfig.json.

npm run clean
Enter fullscreen mode Exit fullscreen mode

This will cleanup the typescript build artefacts (delete the outDir directory defined in tsconfig.json).

Style checker and formatter 

npm run lint
Enter fullscreen mode Exit fullscreen mode

This will run the style checker eslint.

npm run fix
Enter fullscreen mode Exit fullscreen mode

This will fix some of the found lint issues.

bundler

Because we also want to bundle our project we first install esbuild as dev dependency

npm i -D esbuild
Enter fullscreen mode Exit fullscreen mode

Lets test it.

npx esbuild src/index.ts
Enter fullscreen mode Exit fullscreen mode

The output is the bundled file.

You can pass lots of options to the cli interface.
However, using the command-line interface can become unwieldy if you need to pass many options to esbuild. For more sophisticated uses you will likely want to write a build script in JavaScript using esbuild's JavaScript API.

We will do that now.
Lets create a small nodejs binary.

mkdir bin
touch bin/esbuild.mjs
Enter fullscreen mode Exit fullscreen mode

now please copy the following content to the file

#!/usr/bin/env node

import esbuild from 'esbuild';

const build = esbuild.build({
  entryPoints: ["src/index.ts"],
  outdir: "dist",
  bundle: true,
  loader: {".ts": "ts"}
});

await build;
Enter fullscreen mode Exit fullscreen mode

as you can see we will have the outdir dist set. We also need to add this to our .gitignore file.

echo dist/ >> .gitignore
Enter fullscreen mode Exit fullscreen mode

Now lets test it

node bin/esbuild.mjs
Enter fullscreen mode Exit fullscreen mode

As you can see the bundled package is built.

Now we can add a new npm script. Please add a new script within the script part in package.json. Because in addition we want to create the types we also add npx tsc --emitDeclarationOnly --outDir dist/types

...
"scripts": {
  ...
  "posttest": "npm run lint",
  "bundle": "npx tsc --emitDeclarationOnly --outDir dist/types && node bin/esbuild.mjs"
},
...
Enter fullscreen mode Exit fullscreen mode

[option] Package

Now we have the option to create a nice small npm package.
Therefore we need to add a .npmignore file and add some content.

touch .npmignore
echo node_modules/ >> .npmignore
echo build/ >> .npmignore
echo bin/ >> .npmignore
echo src/ >> .npmignore
Enter fullscreen mode Exit fullscreen mode

Also we need to adjust some paths within our package.json

"name": "ts-gts-esbuild",
"version": "0.1.0",
"description": "",
"main": "dist/index.js",
"types": "dist/src/index.d.ts",
...
Enter fullscreen mode Exit fullscreen mode

We can test it now

npm package
Enter fullscreen mode Exit fullscreen mode

This will create a tar archive in your package folder.
You can check it.

Cons

There are lots of pros related to this project setup. But of course there are also some cons.
One of them is that gts is out of the box not properly working with npm workspaces yet gts issue.
But you just need to do the gts init within the repos and adjust some path parameters in some files.

ko-fi

Top comments (0)

Read next

joshuacba08 profile image

Configurando un proyecto de React para producción

Josué Oroya -

henriqueleite42 profile image

TypeScript (and JSDoc) vs JavaScript

Henrique Leite -

abdulkadir_saloum_770fee4 profile image

"TypeScript vs JavaScript: Which One Should You Choose?"

Abdulkadir Saloum -

jacobandrewsky profile image

Five Design Patterns to know in Node.js

Jakub Andrzejewski -