asset-assistant

Introduction

Versions

The 0.0.* versions are for building up the repository and may have changes in the command specification.

Goals

The "assets" program is motivated by the need to automate the copying of assets from npm modules. The typical use case is for images and css files that need to be moved to a location accessible by the web server. It is assumed that javascript code will be packed and run from a single 'root' location. The goal is to keep all asset update instructions out of the source code.

Prerequisites

These programs are intended to be used with the npm package manager. As such they make use of the package.json file and the node_modules directory. All file selections use the Glob package.

Programs

assets

Copy all asset files from source directories and source packages to a specified build directory.

inline

Add <script> and <link> tags to an html file based upon directory contents.

Quick Start

The typical use case is to copy 'asset' files, such as .css, images, sound, etc. , from a package directory to a directory the deployed application has access to. The root package does not require the 'assets' field, and when ommited will only look in packages for 'asset' files.

The 'asset' program will look for an "assets" field in the package.json file. This field can contain the following fields:

• src: An array of strings, listing the file locations to copy files from. Uses 'glob' format.
• dest: The destination directory to copy files to, only relevant to the top level project. Defaults to "build".
• flat: Defaults to false. if true, copy only the files, not the full directory paths. This overrides up.
• up: Defaults to n=1. Omit the first 'n' directories in the tree. Typically this will be the 'src' directory.
• local-src: A list of files that will only be copied if this project is the top level project. Typically for copying .html files to the build directory.

The asset command accepts the following flags

• -v : Verbose, print out packages looked at and files copied.
• -d : Debug, print out more information.
• --clean : remove the directory specified by "dest" in the paackage.json assets field. (Default '/build').
• --fileset=parameter : only copy the local files specified in this parameter ( in the assets parameter).

example package.json (unrequired fields omitted)

"dependencies": {
  "Collection": "file:../Collection",
  "Context": "file:../Context",
  "asset-assistant": "file:D:/project-local/assets",
  "jquery": "^3.3.1",
  "nidget": "file:../Nidget"
},
"scripts": {
  "build-assets": "assets",
  "build-remote": "assets --fileset=local-src",
  "inject-header": "inject src/* src/css/* index.html"
},
"assets": {
  "src": [
    "src/assets/**/*",
    "src/css/dialog.css"
  ],
  "local-src": [
    "src/*.html"
  ]
}

The script 'build-assets' will recursively copy all files in the src/assets directory into the build/src/assets directory. It will also copy 'dialog.css' into the build/css directory. It will then look for the "assets" parameter in the package.json of all dependencies (Collection, Context, etc), if found it will copy files specified by their 'src' parameters and recursively look in their dependencies for more assets. If not found then the recursive search will not follow that branch.

The script 'build-remote' will copy all html files from src/html to build/html, and will not recursive search.

The script 'inject-header' will add a <script> or <link> element into 'index.html' for each .js and .css file found. The paths will be relative to the location of 'index.html'.