Publish

The "publish" app is a utility app that allows you to copy files such as configuration files, static assets, templates, and other files from app directories into your project. It also lets you specify in a custom app what files projects that use your app can have copied into the project directory.

CLI Command

The "publish" app adds the "publish" command to the CLI.

node . publish [...options] appkey

This command does nothing if no options are provided. Options are used to specify what type of files to copy into the project directory and whether or not overwrite files if they already exist.

Options

This table shows the effects of the publish command options. Note that default directories are shown. The "publish" service respects the values of process.env.CONFIG_DIR and any changes to default directories specified in config/disk.js.

Option	Effect
`-c, --config`	Copy a config file from the app into the project `config/` directory.
`-a, --assets`	Copies asset files from the app into the project `assets/` directory.
`-s, --src`	Copies source files from the app into the project `src/` directory.
`-t, --templates`	Copies template files from the app into the project `templates/` directory.
`-f, --force`	Overwrites files if they already exist.

In general, apps specify that the output files in your project directories will match the name of the app. Some examples:

# write the file "config/auth.js"
node . publish --config auth

# (exception) write the direcotries bootstrap/, bootswatch/, fontawesome/, and jquery/ to assets/
node . publish --assets assets

# write the directory "src/auth/"
node . publish --src auth

# write the directory "templates/auth/"
node . publish --templates auth

Each app documents what files it publishes if any.

If you run the "publish" command on an app that doesn't publish anything you specified, nothing will happen. If you run the command without the --force option, no files will be overwritten.

Note that if you run the init.sh script that comes with the starter project, all publishable files from included Carolina apps will be published. If you look at init.sh you will see the publish commands.

Making Files Publishable

You can make files publishable from a custom app by writing a publish.js file in your app directory.

For config files, you can only publish one file and it will automatically publish to config/<your_app_name>.js.

For the other file types, it is best practice to have them in your app directory as sub-directories named assets/, src/, etc. and to publish them to assets/<your_app_name>/, src/<your_app_name>/, etc.

Here is an example app directory:

apps/
  my_custom_app/
    assets/       # publishable assets
    src/          # publishable source files
    templates/    # publishable template files
    config.js     # default config file, also publishable
    index.js      # app service file
    publish.js    # publishability specificaiton

If you wanted to publish the config file as well as the static assets, source files, and templates, then publish.js should look like this:

const path = require('path');

module.exports = {
  // only 1 config file - to config/my_custom_app.js
  config: path.resolve(__dirname, 'config.js'),
  // map of destination (within assets/) to local source
  assets: {
    // make apps/my_custom_app/assets/ publishable to assets/my_custom_app/
    my_custom_app: path.resolve(__dirname, 'assets/')
  },
  src: {
    my_custom_app: path.resolve(__dirname, 'src/')
  },
  templates: {
    my_custom_app: path.resolve(__dirname, 'templates/')
  }
};

This allows you to write your app to expect your app's templates to be located in the project directory at templates/my_custom_app/. For example, in a route you could render a file written as apps/my_custom_app/templates/home.pug with the expectation that a user of your app will run the publish command to copy it into their templates directory into the right place:

router.get('/', (req, res) => {
  return res.render('my_custom_app/home');
});

You should document in a custom app what files are publishable and whether or not running a publish command against your app is required for your app to function as expected.

CAROLINA DOCS