Forem: Duncan Sample

What I use in my craft

Duncan Sample — Thu, 13 Jun 2019 11:38:50 +0000

This article aims to be a list of many of the tools I use for various areas of my software development workflow, in the hope that they help others. I'll try and keep it updated when I find new stuff worth sharing.

Hardware

I’m a bit of a stationary and HID geek. I’ve used a variety of pens, notebooks and keyboards over the years, and have currently settled on these for my everyday needs.

Uni-ball PIN 0.3mm, 0.5mm and 0.8mm fine liners. These use pigment ink, which means they are long-lasting ‘archival’ inks (they don’t fade), and are also resistant to bleeding when using water-based pens to colour over top. The variety of line widths allows for creating a more detailed sketchnote or diagram without having to go over lines multiple times to make them stand out.
Tombow dual brush pens (pastel colours). These are great, coupled with pigment fine liners to highlight parts of a diagram or sketchnote.
Rhodia A5 Wirebound Dot Notepad. I came across Rhodia notepads after listening to The Pen Addict podcast. The paper is smooth, works well with fountain pens, fine liners and felt tip pens, and the added dot-grid allows for writing straight as if on lined paper, as well as allowing diagrams to be drawn with straight lines as if on squared paper. The wire binding gives an easy tearaway option for disposing of temporary sketches, so it works well with my visual way of discussing architectures.
ErgoDox EZ keyboard. Any mechanical keyboard which is compatible with the QMK firmware will give you the opportunity to add layers, macros, and shortcut keys to your keyboard, which can make you more productive and remove the need to constantly switch from keyboard to mouse. I’ve used a Microsoft Ergonomic Keyboard for decades, so didn’t want a non-split keyboard, and when I saw the ErgoDox, I was hooked. I can’t say the quirkiness didn’t add to the the appeal of it, but the comfort it gives is great. I now own two (one DIY, one prebuilt).

Software

Most of my development is done on a MacBook Pro (2015 edition), so I’ll focus OS X. Many of the tools I use, however, are cross-platform, so will work on Linux, and possibly Windows.

iTerm 2. A powerful replacement for the OS X Terminal which supports split-panes and tabs.
ZSH with Oh My ZSH. If you use the terminal a lot, Oh My ZSH will likely improve your productivity. You can customise the appearance of the prompt, as well as enable plugins which auto-complete options within apps such as Git, Docker, Helm, and Node. I use the theme kafeitu.
Visual Studio Code. Over the years I’ve gone from using TextMate, to Sublime Text, to Atom, and now VSCode. It’s a fork of Atom, but although I install a ridiculous number of extensions on both Atom and VSCode, Atom slowed down significantly for me, so I lean towards VSCode now. The added abilities of VSCode for debugging JavaScript code make it great for my work. I’ll cover list some of the extension below.
Vim, a terminal-based editor. I don’t do the majority of my coding in it anymore, but I do still use it for a significant part of my workflow, for quick scripts, remove administration, debugging, etc.
Divvy. A screen divider. There is an Open Source alternative called Spectacle, but it doesn’t have quite the same UX for setting up new shortcuts.

Visual Studio Code extensions

Along with the built-in capabilities of VSCode, I’ve found a bunch of extensions help me be more productive.

Docker provides intelligence for Dockerfiles as well as some useful shortcuts accessible from the command Palette.
EditorConfig, along with the accompanying .editorconfig file within a repository/directory, will ensure that basic formatting is kept consistent. (My current base file can be found here, along with some other useful files for setting up a repo for consistency).
ESLint will highlight code lint issues, and if you set the "eslint.autoFixOnSave": true setting, it will correct the trivial issues whenever you save the file, without the need for Prettier.
Expand Region, If you’re used to control+W in Visual Studio for selecting the current word, line, function, etc. with increasing scope each time you press it, this adds the same functionality to VSCode.
File Icons has some nice icons for lots of file extensions.
GitHub Pull Requests provides a way to view GitHub Pull Requests within VSCode, which is handy for Inner Sourcing/Open Sourcing.
GitLens gives even more access to Git metadata and shortcuts.
Indent Rainbow shows a pleasant colour for each level of indent
Markdown All in One provides a wealth of tools for editing Markdown files
Markdownlint highlights issues you have with your Markdown files
Path Intellisense helps auto-complete relational paths to files
Rainbow CSV colour-codes columns of CSV files to help visual scanning of CSV data.
YAML provides helpful support for YAML file editing, including linting.

JavaScript-specific extensions

CodeMetrics helps by letting you know when your functions are getting a bit long-winded and are in need of refactoring.
Glean helps with refactoring React code
JS Refactor helps with refactoring JavaScript code
NPM highlights issues with packages you depend on
NPM Intellisense helps import libraries by auto-completing package names
Version Lens shows the version of your package dependencies and helps update your references to newer versions
Web Accessibility highlights where you might have accessibility issues in your HTML/React markup

Environment configuration with React & Nginx

Duncan Sample — Thu, 13 Jun 2019 07:13:45 +0000

I’ve been working with React for a couple of weeks, and something I very quickly wanted to know, was how best to achieve environment-specific configuration with a Webpacked app.

For server-side apps, such as Node.js, Ruby on Rails, or even .Net, reading an environment variable and choosing the right config file, or even just reading everything from environment variables is easy, but when your application is a static, minified package of HTML, CSS, and JavaScript, it’s not quite so simple.

There are a few options you have here, so I’ll give a brief description of each, and I’ll describe the downsides that meant I didn’t choose them. First though, I’ll list the parts of my scenario:

React, created using create-react-app, then ‘ejected’
Nginx or potentially other static host (eg. CDN)
Docker
Integrating with a single, remote backend API (for now)

Using React

Webpack on deploy

The documented way seems to be to use process.env.foo in your react app, and let the dotenv plugin for Webpack take care of building the values into the minified code. [1]

On the face of it, this looks reasonable… you configure your Docker container with the environment variables, and just run npm run build in the CMD argument.

For me, this is wholely unacceptable though. The are far too many possibilities for variance, and therefore failure in the process to ‘recompile’ the code for each environment. I need a ‘build once, deploy anywhere' approach.

Another variation on this theme is to build the app with a placeholder in the script, add then use Sed to substitute in the real value on deployment/startup. This again, has too high chance of screwup for my liking.

Host detection

Since all of the environments would have different FQDNs, I could use that as a switch to pick between different set of configuration values.

I discounted this one for two reasons. Firstly, this would mean building in the configuration for all of the environments, exposing the existence and addresses of internal infrastructure and giving away some amount of development process. Secondly, if the browser misinterprets the host name somehow, it could fail inconsistently.

There’s also a slight annoyance with local testing conflicting with a user loading the site having saved it to their machine for looking at later, however, this isn’t a huge concern as other things would break.

Using Nginx configuration

Since the React tooling didn’t appear to have a decent answer, my next thought was to use Nginx — the web server if use to host the built site — to provide the configuration.

I saw a suggestion for doing the placeholder replacement approach using Nginx’s sub_filter module, but I disliked that for the same reason as above.

Separate config file

Of course, the next step was to make the configuration a separate file and somehow (I’ll touch on at the end) bring that file into the app when it’s loaded into the browser.

Something that’s done with server-side code is to store config files outside the public files directory, and then use the environment variable (eg. NODE_ENV) to pick the right config file, and serve that file up as a generic /config.js endpoint. So can we do that with Nginx?

Short answer, no. Long answer, yes, but you’re apparently not supposed to, so they make it hard.

Out-of-the-box, Nginx doesn’t support using environment variables inside most configuration blocks.

You can use the Lua or Perl modules, but that will require installing those modules, making your Docker image bigger, and at that point your site stops being ‘static’ if you’re having to use runtime code.

Generate nginx.conf

Several answers on StackOverflow suggest generating the nginx configuration on deployment/startup. Ranging from Sed, and envsubst, to erb (Embedded Ruby) and other scripting languages.

String replacement methods, like Sed were out, solely for the possible inconsistency when dealing with complex config files. The necessity to run many times for different variables also doesn’t make it easy.

Scripting languages like erb were out as I’d have to install whichever one inside the Docker image in order to use it, and that’s unnecessary bloat (as well adding to the security risk). There’s also the issue with some scripting languages that usage of special characters (eg. $) in the nginx.conf itself might be interpreted, rather than left as literal strings in the config.

Copy the app’s config file into place

Perhaps the simplest approach, but easy to neglect, is to have a simple shell script run prior to Nginx starting. That script reads the environment variable and copies the relevant file from an environment-specific directory to a generic file in the static site directory.

cp /config/$ENVIRONMENT.json /app/config.json

If you’re passing the actual configuration values in, rather than picking a pre-stored file, there’s also the option to generate the config file using a simple echo command

echo ‘{“foo”:”$FOO”}’ > /app/config.json

Copying a pre-made file is currently my preferred approach. There’s always room for error, but this way doesn’t touch any brittle/complex server configuration, and leaves the server as dumb as possible at runtime. You could even run your site from S3/similar, rather than Nginx, if you wanted.

The whole setup ends up looking something like this:

#Dockerfile
FROM nginx:latest
COPY nginx.conf /etc/nginx/nginx.conf
COPY build /usr/share/nginx/html/
COPY config/client-side /usr/share/nginx/config/
COPY launch.sh ./
RUN chmod +x launch.sh
CMD ./launch.sh

#launch.sh
cp /usr/share/nginx/config/$ENVIRONMENT.json /usr/share/nginx/html/config.json
nginx -g "daemon off;"

#nginx.conf (snippet)
...
http {
...
    server {
    ...
        location / {
            root   /usr/share/nginx/html;
            index  index.html;
        }
    }
}

Including the config in the site

The other side of things that was virtually unexplained, was how to get the config file to stay separate to the main application code, but still be included.

Code splitting

I tried to see if I could get Webpack to leave the config file out of the bundle, and require it at runtime, but I gave up quickly when it wasn’t obvious. I’m sure there’s probably an elegant way to do it here if I could be bothered to find it.

Script tag

Putting the config.js file as a <script> tag in the HTML template worked, but I’d have to rely on a blocking script loading in order to make sure the config was loaded before the application code.

Request it

The easiest way I could think of was to make a module in the application that would make an HTTP request for a relative path /config.json and provide the response to the rest of the application.

The added benefit of requesting it is that I can deal with error handling, as well as a loading spinner, if I wanted one.

The end result

After playing with all of the options, the easiest, as well as more resilient option seems to be to keep separate config files per environment, and request it the first time it’s used in the front-end.