Local Dev Setup

An overview of how my dev setup works, the tools and what they do

Local development system (e.g. when coding with VSC - Visual Studio Code) can be run with two terminals, one to execute 'npm run server' and the other to build the site 'npm run build' (these scripts - build and server - are defined in the package.json file). The site will then be served locally from 'https://localhost:3000'. Running locally depends on .env having NODE_ENV = 'development', whilst the live code in Azure must have this setting as 'production'. Npm stands for 'Node Package Manager', a service which hosts open source software and locally allows you interact with said software. Using https for a localhost server relies upon globally installed package 'https-localhost', otherwise it only works as http by default, which prevents service worker functionality.

Create code with Visual Studio Code

VSC - Visual Studio Code is a free Integrated Development Environment (IDE) created by Microsoft. It is basically a text editor, as that is all code is - but with a wide range of features to make the text easier to read as code!

Installing stuff

The local development system has a number of components, which can be setup as follows:

  • Install:

    ○ VSC, which can usefully be extended with a range of options, such as:

    Prettier
    Azure
    Bracket pair colorizer
    Code spell checker
    ESLint
    IntelliSense for CSS
    Markdown preview
    Material or One Dark Themes
    Npm IntelliSense
    Pug to HTML
    Puglint
    Settings sync
    Many more!

    ○ Node v10.16.3 (at least) and globally, also gets you NPM

    JSDocs (globally)

The Terminal

  • Terminal - is basically a Windows cmd prompt (alternative being PowerShell), in which you can use 'the command line' to navigate around folders, create files, run Windows or local script commands etc. In VSC, there is a built-in terminal which works just the same but more accessible

  • There are variants on the type of terminal VSC provides but there's little need to move beyond the default for most purposes

Node and NPM

Node (NodeJS) - the core of a web browser that can run independently, so able to host apps or run scripts https://nodejs.org/en/

NPM - Node Package Manager https://www.npmjs.com/ is a service that hosts open source software packages you can use in your app, and also manages those packages locally, mostly via a file called 'package.json'. A lot of the magic of JavaScript is managed by JSON files, and it is useful that this format is consistent with how JavaScript defines data objects within code as well - the format is basically interchangeable

Package.json

Package.json defines the core definition (e.g. name, version) and structure of a web app (e.g. which associated packages are needed) plus options for building the code (if any)

JSDocs

A documentation system based on translating code comments into a centralised webpage

Github

Git is a fundamental system for code storage, change tracking and version control and typically integrated with github.com or similar service. There are many good resources around on the subject, I get on fine using GitHub Desktop as a one-man-band operation.

.gitignore

An important config file (e.g. for VSC) is .gitignore, which defines a list of files and directories that should not be added to a code repository (project) in github.

Environment variables

.env files are useful for defining configuration information that is secret - e.g. database keys, passwords etc. that your app needs when running locally. These data will be configured in parallel within the web host (e.g. the settings of an Azure web app). Never include this file in the data sent to a code repository - that's what the .gitignore file is for

Environment variables in .env make the localhost server work

  • Secret data not shared publically (in the browser or in code repositories etc.)

  • Settings specific to the web app such as database access keys, API passwords etc.

  • Parallel variables configured in web server settings

  • The dotenv package is used to 'run' a local .env file

cpx

Managing where files go if Parcel doesn't know what to do...

Bundling up to publish

In order to keep code tidy when it's running in a browser, a 'bundler' is used such as Parcel or Webpack.