Nodewood relies on a collection of tools in order to simplify and speed up development. This section of the guide will explain those tools and how to install them on your system.
You will require at least 2GB of RAM to run Nodewood, so please make sure your Docker "Memory" (under "Resources") is set to at least that, or make sure the system (or VM) that you are running on has at least that much memory available to it.
Yarn is an alternative package manager to NPM. For the most part, they are interchangeable, but Nodewood uses Yarn to set up workspaces (opens new window). This allows Nodewood to specify packages it uses in its own
package.json file, and your app to specify packages it uses in its own
package.json file. This makes it easier to update Nodewood packages without clobbering your application's packages. (i.e. if Nodewood stops using a package that your package continues to use, Nodewood removing it from its own
package.json won't break your application).
- Visit https://yarnpkg.com/getting-started/install (opens new window)
- Follow the installation instructions to install yarn from NPM. Skip the "Per-project install" section, as Nodewood still uses Yarn 1.
If you are installing Yarn on Windows, you must restart your computer after installation, otherwise globally-installed yarn modules (like the Nodewood CLI!) won't work. This is a reported Yarn issue (opens new window).
You may also need to add your Yarn global binary folder to your
PATH (opens new window), if you get an error like
'nodewood' could not be found or
The term 'nodewood' is not recognized.
Docker is a tool that allows for the packaging of software applications into lightweight containers, and then running those containers in a reasonably low-effort way. Nodewood uses a small collection of Docker containers during development to run a PostgreSQL database and Nginx web server, as well as watchers for the Express API and Webpack UI portions of Nodewood itself. Using Docker means you don't need to manually set up PostgreSQL and Nginx, and you don't need to have multiple terminal windows open to monitor the API and UI processes separately.
Installing Docker is thankfully reasonably easy and well-documented. Choose your installation instructions based on your operating system:
- Install Docker Desktop on Windows (opens new window)
- Install Docker Desktop on Mac (opens new window)
- Install Docker Engine on Linux (opens new window)
You will also need to create an account on Docker Hub (opens new window) and then sign in on Docker Desktop. If you find that Docker is abruptly halting while launching the Nodewood containers, it is likely because you are not signed in and it cannot find your authorization information.
If you are not yet familiar with Docker, Docker for beginners (opens new window) can help you get comfortable with the basics, however I would appreciate feedback about what aspects cause problems, so that I can improve them or write documentation to help.
If you are running on OSX, you might find Docker's performance a bit... poky. This is because the default volume mount (i.e. how your project folder is mounted inside the Docker container) is slow. Thankfully, we can use an app called Mutagen (opens new window) to SIGNIFICANTLY speed up that mount speed, by double (or more)!
Check out our article titled How To Speed up Docker on MacOS by 100% or more (opens new window) for an explanation of how it works, then how to apply it to your Nodewood project. You'll be glad you did!
The default terminal for your system may make your life more difficult than it has to be. For example, the default Windows terminal requires you to right-click and select "Paste" to copy and paste -- your expected keyboard commands won't work. Here are a list of alternative terminals that will improve your development experience:
# Windows: Windows Terminal
Microsoft helpfully provides Windows Terminal (opens new window) for free on the Microsoft Store. It adds tabs, starts you off with a sane font size, and has working keyboard shortcuts for copy/paste.
# OSX: iTerm2
iTerm2 (opens new window) is jam-packed with a variety of improved features (opens new window) over the default OSX terminal. Of particular note is the ability to bind a system-wide hotkey that will bring the terminal to the forefront, for instant access.
# Linux: You probably have a favourite terminal already
Oh no, I'm not getting into this fight. There are dozens of really great terminal emulators for Linux, and the default installed with your OS is likely already more than sufficient for a really great experience. You're already a winner.
# Create a new Nodewood Project
New projects are created with the Nodewood CLI tool. To install or update the tool:
yarn global add @nodewood/cli
After, follow these steps to create and spin up a new Nodewood project:
- Log in at Nodewood (opens new window) and click on "Projects" in the sidebar. Click the "New Project" button, enter a project name, and click "Create". Copy the API Key and Secret Key returned to you.
nodewood new DIRwhere
DIRis the directory in which you want to create your app. Paste in your API Key and Secret Key when asked. Let it download and extract files, and run the installers.
You may see an error similar to this when creating a new project:
error firstname.lastname@example.org: The engine "node" is incompatible with this module. Expected version "^16 || ^15 || ^14 || ^13 || ^12 || ^11 || ^10 || ^9 || ^8 || ^7 || ^6". Got "17.3.0"
This is because Nodewood currently uses a library that includes a version of
eslint-import-resolver-webpack that is not yet aware of Node 17, which would be the version you have installed. Install a Node version manager like nvm (opens new window) and ensure you're using a version of Node that's compatible. (
nvm use 16 should work.)
- Set up your mailer. This is optional, but can make your life easier. If you don't set up a mailer now, emails will be logged to your terminal, and links for account activation/password reset can be copied from there.
- Change to your new application's folder:
DIRis the directory from before.
- Run initial database migrations with
- Run the Nodewood development server with
This will start a PostgreSQL instance, an Nginx instance, the API Express server, and the Webpack UI process. It can take a while for all these processes to start up, but the UI process is usually the last one to complete. You'll be able to tell when you see the following UI log line:
ui_1 | DONE Build complete. Watching for changes...
Provided you are not currently running a webserver on your host machine, you can now access your Nodewood project at https://localhost (opens new window). (If you are running a webserver on your host machine, you can either halt it while developing your Nodewood project, or alter the
ports entry in the
nginx section in
You will need to accept the self-signed certificate to continue, though you will only need to do this once. If you are on Google Chrome, accepting the certificate is a bit... non-standard. You need to visit chrome://flags/#allow-insecure-localhost and change "Allow invalid certificates for resources loaded from localhost." to "Enabled". Alternatively, if you don't want to change settings in your browser, just allow it for the one site, you can click anywhere on the certificate warning page, and then type in "thisisunsafe". This instructs Chrome to accept the "unsafe" self-signed certificate.
Despite the various browser warnings, this poses no actual security risk, since it is only a development application, and one under your control.
Both the API and the UI will watch for changes as you develop, and will restart/recompile accordingly. You will need to give it a few seconds after you save your changes, but never especially long. You can always check back on your terminal window to see if the restart/recompile has completed.
Every process logs to the same window, which might be confusing at first, but each line is prefixed by what process caused it, and coloured uniquely, which should help reduce confusion.
You may notice the following error on first run:
error 'wood' should be listed in the project's dependencies.
This sometimes occurs on first run. Use Ctrl+C to close and then re-run
nodewood dev, and it will go away. Alternatively, you can use lazydocker (opens new window) to restart only the