The code for this post is available here.

Assumed knowledge: some prior experience with the terminal and ssh keys.

There are 6 main components to creating this project so that it is reusable, and can be straight forward to develop on any machine.

Open your terminal, and create a new directory. This is where the boilerplate will be stored.

VSCode

Before you begin a project, it’s necessary to have an IDE. As of this post, it’s become almost standard to use VSCode for web development. There are lots of nice extensions and tools that provide a very good developer experience, and it’s free.

  • Head over to the VSCode website, download it, and ensure it is installed.

  • Open VSCode. Within the app, open your boilerplate directory.

  • Go to the extensions tab and install these two extensions:

  • Create a new file, call it README.md, and put information about your project in this file.

  • Create a directory, call it .vscode. Inside that directory, create a file and call it settings.json. Copy the contents from this linked page into the file.

Node

Node (or NodeJS) is a JavaScript runtime that is used for “building” our code. It’s also necessary before continuing, as it will provide the packages needed to serve as the basis for the boilerplate. It is used via the terminal, and is available on all operating systems.

  • Head over to the NodeJS website, download it, and ensure it is installed.

  • In the terminal, in your boilerplate directory, run: npm init -y.

  • You should now be able to see a file: package.json.

Snowpack

There have been many build tools over the years that have made it increasingly easier to compile various JavaScript packages and files together so that they run correctly in the browser. Snowpack is very fast for development, and is fast when it builds (it uses esbuild under-the-hood).

TypeScript

Although JavaScript is great for quickly putting together web applications, I find that it doesn’t scale very well as projects grow in size. TypeScript gives your JavaScript types, which can primarily help to make you write code that is easier to understand, which in turn helps the IDE give you nice tools to help you write code faster.

  • Install TypeScript: npm install ---save-dev typescript.

  • Create the config file: node_modules/.bin/tsc ---init.

  • Replace the contents of the tsconfig.json file with the contents from this linked page.

  • Create a directory named src. In this directory, create a file named index.ts. You can write any valid TypeScript code in this file, as well as import other files within the src directory, or installed via npm.

  • Create a directory named typings. In this directory, create a file named index.d.ts. In this file, you can define types to be used throughout your TypeScript files in the src directory.

ESLint

In order to make code automatically look consistent and report when you’re doing something wrong, the linting tool ESLint is very helpful. It operates in both the IDE and within the code building tools. The rules provided here are opinionated as to how the author prefers code to look, but you can customise them by setting any of the rules.

  • Install ESLint and plugins: npm install ---save-dev eslint @typescript-eslint/eslint-plugin @typescript-eslint/parser.

  • Create a file named .eslintrc and copy the contents from this linked page into the file.

  • Create a file named .eslintignore and copy the contents from this linked page into the file.

Github

In order to manage the development process, it’s useful to use a version control system, such as git. Github is a service that allows cloud hosting of a git repository, as well as hosting of static sites, such as the one this project will create. Ensure you have ssh set up with a valid public and private key available in your terminal’s environment.

  • Follow the git guide on Github to get set up with both.

  • Initialise the project as a git repository: git init. Remember to configure the email address and name for the git commits.

  • Create a file named .gitignore and copy the contents from this linked page into the file.

  • Create a new repository on Github, and follow the instructions to add the respository URL to the boilerplate project.

  • In the repository settings, following the instructions to set the main branch docs directory as the pages' source. You will need to have commit and pushed your files beforehand in the previous step to do this.

Before next steps

Everything is now set up to continue on with posts that expand on this code. It is possible to test out the current set up by:

  • Placing a console log command in the src/index.ts.

  • Running npm run build in the terminal.

  • Adding some content to the README.md file.

  • Commit the current files, with:

    • git add .

    • git commit -m "initial commit"

  • Pushing the commit to the repository, with: git push -u origin main

    • Note, this might be called master instead of main if the default git branch name was preserved.
  • Visiting both the Github repository you created, and the pages URL that was generated.

Next steps

Code Design for Web Apps Using Web Components and Observables and No Frameworks