CLI Tools

When you install Commonplace, a set of command line tools are installed. They should be available via the commonplace command. Running which commonplace should output a value; if it doesn't, you probably need to run npm install -g commonplace.

If you're looking for information on Damper, see that article.

Usage:
  commonplace <command>

Commands:
  install          Run this command to instantiate commonplace.
  init             This will set up a freshly cloned copy of commonplace.
  update           This command will update commonplace modules.
  ignore           This command will add a file to the ignored files list.
  extract_strings  This command will extract strings into a `.pot` file.
  langpacks        This command will generate langpacks out of `.po` files.
  clean            Clean up static files, templates, and langpacks.
  compile          Generate CSS from stylus and JS from templates.
  includes         Combine and minify all the CSS and JS assets.
  lint             Lints the current project.
  fiddle           Installs Commonplace project dependencies.

install

Running this command in an empty directory will install the skeleton for a commonplace project. The following structure will be produced:

root
|- src
   |- .commonplace
   |- media
   |  |- fonts
   |  |  |- ...
   |  |- js
   |  |  |- ...
   |- templates
   |  |- ...
   |- tests
   |  |- ...
   |- index.html

The .commonplace file is the manifest used to track information about the project.

This command will not overwrite existing Commonplace projects if the version is different, however it will overwrite the files if the version is the same. This command does not respect commonplace ignore.

init

If you've just cloned a Commonplace project, running commonplace init will set it up locally. This means it will copy any *.dist files to their non-.dist equivalents. E.g.: settings_local.js.dist will be copied to settings_local.js. If the non-.dist version already exists, it will not be overwritten.

This should be run on any fresh clone of a Commonplace project. It will only run in an existing Commonplace project.

update

This command will update a Commonplace project's source files to the version of Commonplace installed on the system. The following file types will be updated:

• .js
• .dist
• .woff
• .svg

HTML and CSS files will not be updated.

If the --npm flag is passed to commonplace update, Commonplace will automatically run npm update -g commonplace to download and install the latest version of the package before performing the update.

Files that have been ignored via commonplace ignore will not be updated. This list is drawn from src/.commonplace in the ignore field. It is expected to be a list of paths relative to the src/ (or hearth/) directory.

This command will complete silently if the version is the same, and can only be run in an existing Commonplace project.

ignore

Running commonplace ignore <path>[ <path>...] will add each path to the ignore field of the Commonplace manifest in a project. The following commands will work:

cd /opt/myproject

# Relative to the root
commonplace ignore src/media/js/foo.js

# Relative to the source directory
commonplace ignore media/js/foo.js

This command can only be run within a Commonplace project.

extract_strings

This command will run the L10n extraction script on the project. Strings will be extracted from HTML and JS files and stored in a gettext-friendly directory (locale/). See the L10n page for more.

This command can only be run within a Commonplace project.

langpacks

This command will run the L10n compilation script on the project. The directories in locale/ will be iterated and JS language packs compatible with src/media/js/l10n.js will be compiled and placed in src/media/locales/. See the L10n page for more.

This command can only be run within a Commonplace project.

clean

Removes temporary or compiled files from the repo. This includes:

• _tmp/
• src/templates.js (compiled templates)
• includes.js and includes.css
• src/media/locales/*
• src/locales/* (legacy locales directory)

Note that compiled CSS (*.styl.css) is not removed by this command.

This command can only be run within a Commonplace project.

compile

• Compiles all CSS files from Stylus. These files are placed in the same directories as the Stylus files, named foo.styl.css.
• Compiles all templates with Nunjucks into src/media/templates.js.

If the version of the project is built using a different version of Commonplace than the one installed, a warning is generated. In this case, the resulting files may not work as expected. This command can only be run within a Commonplace project.

includes

Generates an includes.js and includes.css file from compiled code. commonplace compile is run automatically. These are generated in the following ways:

JS

All JS files are concatenated (excluding language packs) and injected into amd.js. The file is then uglified. This contains templates, as well.

CSS

All CSS files are compiled from stylus, then concatenated. The file is then minified with clean-css.

lint

Runs JSHint against all JavaScript files in the current codebase, with two exceptions:

• Any file in a directory that contains lib/ will not be linted.
• templates.js will not be linted.

The only JSHint configuration provided is {"boss": true}, which disables warnings for assignments where comparisons were expected (Commonplace sometimes assigns variables in the expression field of an if() statement, or assigns a variables in the comparison field of a loop).

A list of all errors will be printed to stdout and the process will return a status code of 1 if any lint errors were found.

fiddle

The fiddle command is used to install Commonplace projects that are dependencies of larger projects. For instance, a repository providing an API might list the web front-end (which is powered by Commonplace) as a dependency.

This command should be run in the same directory as the package.json file for a project. The package.json file is expected to contain a field named "commonplaceDependencies". This field should contain an object mapping git URIs to objects containing information about the repository at the URI:

{
  "commonplace" {
    "git://github.com/mozilla/fireplace.git": {
        "name": "fireplace",
        "symlinks": {}
    },
    "git://github.com/mozilla/rocketfuel.git": {"name": "rocketfuel"}
  }
}

All listed dependencies must include a name field. This is the name of the directory that the project will be cloned into. All projects will be cloned into ./commonplace_projects/, so that directory should be added to the .gitignore file. For instance, a dependency with the name "foo" would clone into ./commonplace_projects/foo/.

If a symlinks field is provided, it is used to establish symlinks into the project. The field is expected to be an object, where keys are paths within the dependency (where the symlink will point to) and the values are paths within the parent project (where the symlink will be created).

If commonplace fiddle is run and the dependencies have already been cloned, the command git pull -r origin master will be run inside them.

After cloning or pulling, the equivalent of the following commands will be run (in the order shown):

commonplace clean
commonplace init
commonplace includes