CLI / Scripts

Since Nodewood makes extensive use of the cascading filesystem concept, any scripts you write will need to be properly bootstrapped with Nodewood's require system, otherwise any imports of files that start with # will fail. Rather than have you write that bootstrap code every time, Nodewood provides an entrypoint specifically for scripts.

WARNING

Make sure you have Nodewood CLI version 0.16.2 or higher in order to use this feature.

Creating scripts

To create a new script, use the Nodewood CLI:

nodewood add:script FEATURENAME SCRIPTNAME

For example:

nodewood add:script posts IndexPosts

This creates a new script in app/features/posts/cli/scripts/IndexPostsScript.js, and a scaffolded test file in app/features/posts/cli/scripts/__tests__/IndexPostsScript.test.js.

Running scripts

The entrypoint for all scripts is app/cli/script.js, but in development at least, there is a helper to make using this entrypoint easier.

In development via the Nodewood CLI

To run a script in development, use the Nodewood CLI:

nodewood script SCRIPTNAME ARGS

For example:

nodewood script features/posts/cli/scripts/IndexPostsScript --fastIndex

This will run the script from #features/posts/cli/scripts/IndexPostsScript with the option fastIndex: true, using the cascading filesystem to ensure that a script in app is loaded before a similarly-named script in wood.

In production via script.js

The nodewood script command runs via Docker, but in production you will likely be running directly on a VM instance. (If you are using Docker in production, you can ignore this section.)

To run a script directly, invoke script.js directly. From the root folder:

node app/cli/script.js SCRIPTNAME ARGS

For example:

node app/cli/script.js features/posts/cli/scripts/IndexPostsScript --fastIndex

This will run the script from #features/posts/cli/scripts/IndexPostsScript with the option fastIndex: true, using the cascading filesystem to ensure that a script in app is loaded before a similarly-named script in wood.

Testing scripts

Scripts export a run() command that is imported into script.js, but can also be imported into a test file. There should be a test harness included for your generated script files in __tests__/ScriptName.test.js that imports that run command and uses it in an example test.

You can run these tests like any other tests:

nodewood test SCRIPTNAME

For example:

nodewood test IndexPostsScript

This will run any tests with IndexPostsScript in the name, which will catch the features/posts/cli/scripts/IndexPostsScript.js script file we mentioned earlier in this documentation.

Script options

The following script arguments modify important aspects of how your scripts run:

--format

Any errors thrown by your script are caught by the the script.js wrapper and logged as output. By default, this output is colorized using chalk (opens new window) (which you can use in your scripts as well, to add coloring to your output). However, you may not want this coloring, as on non-ANSI terminals, these colors are not displayed, and the escape codes for color can be confusing to read.

You can specify --format=plain to output the logs as just plain text, no color codes.

Alternatively, you can specify --format=json to output the logs as JSON objects, in the same format as API logs. These logs are much easier for machines to parse, allow you to append objects to the output instead of just raw text, and can be "pretty-printed" by appending | npx pino-pretty to your log output command.

For example:

cat script.log | npx pino-pretty

--emailOnError

If you want your script to email you if there has been an error, set this option to true.

For example:

nodewood script features/posts/cli/scripts/IndexPostsScript --emailOnError

By default, it will send email to the supportEmail address specified in your email config file.

--errorAddress

If you want to change the email address used to send you error messages when sending an error, set this option to that address.

For example:

nodewood script features/posts/cli/scripts/IndexPostsScript --emailOnError --errorAddress=new@address.com