# CLI Tool
The Nodewood CLI Tool (opens new window) is designed to help you easily build, develop, and maintain your Nodewood project. It wraps common functionality, meaning you don't have to learn the ins and outs of other command-line tools (like Knex or Docker), and performs advanced tasks (like synchronizing your subscription configuration with Stripe's servers).
Install the CLI tool globally to help you develop inside your Nodewood project:
yarn global add @nodewood/cli
Current version: 0.17.1
# Creating a new project
To create a new Nodewood project, consult the Create a project section of the Installation page of the documentation.
# Running/Rolling back migrations
While Nodewood uses MassiveJS (opens new window) 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 (opens new window). To run existing migrations, run:
nodewood migrate
This will run all migrations from the app/migrations and 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:
nodewood rollback
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 (opens new window).
# Seeding your database
Running migrations will start you with an empty database, which isn't always what you want. For example, for local development, you may want to have some sample users/teams already created so you don't have to create and verify a new user every time you recreate your database.
Seed files solve this issue. Development seed files are located in app/seeds/development, and a sample file that creates two users on their own team (each with the password "password") is located in that folder as dev.js. You can modify this file as you see fit in order to set up the initial state of your development database.
To run seed files, just run nodewood seed from your project folder (after running migrations), and it will run all files in the app/seeds/development folder.
# Starting the Nodewood development server/watchers
From the root of your Nodewood project, you can start the development server processes with:
nodewood dev
This will use docker-compose to start a PostgreSQL process, an Nginx process, the Express API process, and the Webpack UI process. The API and UI processes will be running in "watch mode", and will automatically restart when relevant changes are detected.
You can tell when the API process has finished loading/reloading when you see the following line:
api_1 | [1604162327094] INFO (95 on 94cc2d49b5a7): Express app listening on port port 3000. 🌲
You can tell when the UI process has finished loading/reloading when you see the following line:
ui_1 | DONE Build complete. Watching for changes...
When you start the development server the first time, you will need to wait until both log lines have been emitted before accessing the server, though the UI one will be the last to log in nearly ever case.
Provided you are not running a web server on your host machine, it will bind to standard http/https (80/443) ports, and you can visit your site by going to your browser and entering https://localhost. You will need to accept a certificate exception, since the development server runs using a self-signed certificate, but since this server is for development only and is completely under your control, this does not actually pose any risks.
If you are running a web server on your host machine, you will either have to shut it down while developing with Nodewood, or modify the Nodewood docker files to run on non-standard ports.
# 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.
# Ejecting files from the wood folder
Since a file in the app folder will supercede a file in the same location in the wood folder, you will occasionally want to add and modify your own versions of these files. You can use the eject command to copy a file from the wood folder to the correct location in the app folder automatically. The easiest way to do this is to find the include/require statement in your files, copy the location, and paste it into your terminal. So from:
import LoadingSpinner from '#ui/components/LoadingSpinner';
You would run the following command:
nodewood eject ui/components/LoadingSpinner
This will copy the file from wood/ui/components/LoadingSpinner.vue to app/ui/components/LoadingSpinner.vue. This file will now be used every time you import #ui/components/LoadingSpinner, including all the changes you make to it.
If you eject a file and then get an error about a module cannot be found, see this note about eject and workspaces.
# Upgrading your Nodewood installation
To upgrade your local Nodewood installation (the wood folder), run:
nodewood up
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.
Occasionally, you may find that the Upgrade command will require you to have a more-recent version of the Nodewood CLI tool, which you can get by running:
yarn global add @nodewood/cli
This will ensure you have the latest version of the nodewood tool, and access to all the updated commands detailed in this documentation.
# Running tests
In order to run your project's tests, run:
nodewood test
This will spin up a temporary docker container, run any files with .test.js or .spec.js as their extension, then remove that container.
To run a specific test file (or pattern), you can append that filename (or pattern) to the command, like nodewood test app/features/foo/api/controllers/__tests__/BarsController.test.js.
# Adding a Prefix to your Tailwind CSS classes
Certain CSS frameworks use classes that can conflict with Tailwind's. Thankfully, Tailwind comes with the option to define a prefix (opens new window) to avoid these conflicts. Nodewood is developed using the base class names, but you can rename these classes to use your chosen prefix with the following command:
nodewood tailwind:prefix
This will request a prefix from you, ensure it ends in a hyphen, and update all .vue files in app and wood with the provided prefix.
Note: If your app/tailwind.config.js file contains a prefix entry, this entry will automatically be prepended to Tailwind classes in wood whenever you run nodewood up.