# CLI Tool
The Nodewood CLI Tool is designed to be installed globally to help you develop inside your Nodewood project:
yarn global add @nodewood/cli
# Creating a new project
# Connecting to the Nodewood development VM
Nodewood uses Vagrant and VirtualBox to launch an instance of Ubuntu, and then Ansible to configure it. While you will probably want to learn about those tools in their own right, you don't need to really know more than that to get started.
Once you have a Nodewood project created, change to the root directory and then run:
This will launch the VM if it is not yet running, then connect to it. Once connected, your project's code is shared in the
~/code folder. Any changes you make to your host system's code will immediately be reflected there.
# Running/Rolling back migrations
While Nodewood uses MassiveJS for database access, it doesn't come with a built-in migrations library. So for this purpose, we use the excellent migrations capabilities of Knex.JS. To run existing migrations, run:
This will run all migrations from the
wood/migrations folders. You can optionally add
test to the end of the command (
nodewood migrate test) to run migrations against the test database.
To rollback the most-recent set of changes, run:
Again, you can add
test to the end of the command (
nodewood rollback test) to rollback the most recent set of changes from the test database.
This should handle the vast majority of cases you'll encounter for migrations, but should you require anything more complex, you should consult the Knex.JS migrations documentation.
# Starting the Nodewood development server/watchers
Once connected to the VM and in the
~/code directory, you can start the development Express server with:
nodewood dev api
This will begin serving your application from the VM's IP address (defaults to
192.168.33.13). It is recommended that you add that IP address to your hosts file to make it easy to connect, but you can always just visit
https://192.168.33.13 in your browser to start.
Any API code you alter will trigger a reload of the Express server, so you may have to wait a second or two in between making changes and testing.
If you are going to be making changes to your UI code as well, you'll want to start the UI development watcher. In another window, connect to the VM, change to the
~/code directory, and run:
nodewood dev ui
This will build the UI and start a watcher that works much the same way the API watcher works - when you change UI code, it will rebuild the UI. It also can take a few seconds in between making changes and finishing the rebuild.
# Watching UI locally
You don't necessarily have to run the UI watcher on the VM - it's just already configured for you to do so. Since the UI doesn't rely on connecting to the database on the VM, you can run it locally to reduce the average build time when making changes.
A caution about building locally - do not run
yarn install locally unless you are using the same OS as the development VM (Ubuntu), as certain shared libraries may install binary code that is not compatible between OSes. Always run
yarn install from the development VM. If you do accidentally run
yarn install from your host OS, all is not lost. Simply run
rm -rf node_modules from the root of your Nodewood project, then run
yarn install from the development VM.
# Adding new files to your project from a template
You can always add a new file to your project by creating a blank file in the correct location, but if you want a template to start from, you can use the
nodewood add command.
For more information on how this command works, refer to the documentation on the different file types, as they will have detailed information on how to add templates there.
# Upgrading your Nodewood installation
To upgrade your Nodewood installation, run:
This will first check what upgrade version your license gives you access to, present the migration notes for all versions between yours and that version, and confirm that you wish to upgrade. Then, it will replace the contents of the
wood folder in your project with the upgraded contents.
For this reason, it is strongly recommended to never change the contents of the
wood folder, as it could be removed at any point.