auturge/json-trim

Table of Contents

• About
  • Motivation
• How to Install
• Supported Command-line Arguments
• Common Options
• Configuration Files
  • The configuration object
• Examples
  • Example: from the command line
  • Example: a simple config file
  • Example: a more advanced config file
• Contributing and Internal Documentation
• License

About

When building a JS/TS library, I find that I often want separate versions of my package.json for the project source and the finished library. I don't usually want to include my build scripts or devDependencies in the final product, but I also don't want the name, version, or other metadata to be out of sync.

json-trim provides a method of easily copying a pared-down version of a json file to another file location.

Motivation

For a specific example, let's pretend that I'm building a new TypeScript library called @auturge/maximus, which I plan to publish to a package repository (e.g., the npm repository). My development process includes:

1. lint, test, and build (into the dist folder),
2. update and copy relevant files (package.json, README, CHANGELOG, LICENSE, etc.) into the dist folder,
3. run some pre-publishing checks, and
4. publish to the package repository (from the dist folder).

Typically, my dist folder includes everything that I intend to publish, so the project tends to take this shape:

maximus
├── dist/
│   ├── package.json
│   ├── README.md
│   ├── CHANGELOG.md
│   ├── LICENSE
│   ├── maximus.js
│   └── maximus.d.ts
│
├── src/
│   ├── index.ts
│   ├── ...
│
├── test/
│   ├── ...
│
├── package.json
├── README.md
├── CHANGELOG.md
├── LICENSE
├── ...

json-trim makes step #2 in the process above less cumbersome: it copies the root package.json file into the dist folder, and removes any keys that I don't want to publish from the copy.

NOTE: I still need to update the version property before publishing.

For example, assume that the root package.json looks like this:

{
  "name": "@auturge/maximus",
  "version": "1.0.0",
  "description": "auturge/maximus - does a thing!",
  "author": "auturge",
  "license": "MIT",
  "bugs": {
    "url": "https://github.com/auturge/maximus/issues"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/auturge/maximus.git"
  },
  "homepage": "https://github.com/auturge/maximus",
  "main": "maximus.js",
  "files": [
    "README.md",
    "CHANGELOG.md",
	...
  ],
  "engines": {
    "node": ">=12.8.1"
  },
  "scripts": {
    "build": "npm run ~rollup",
    "test": "npm-run-all ~test:clean ~test:run",
    ...
  },
  "oldScripts": {
    "build": "npm run ~webpack",
    ...
  },
  "devDependencies": {
    "@auturge/testing": "latest",
    ...
  }
}

There are certain portions of this that will not be useful without the source code, which I don't publish to the package registry. In this case, I don't need to publish "scripts", "oldScripts", or "devDependencies"... they are helpful during the development process, but would be cruft if included with the distributed library.

So I want to copy my package.json, while trimming out those keys.

How to Install

The following commands will install json-trim:

npm install --save-dev @auturge/json-trim

or

yarn add @auturge/json-trim --dev

Supported Command-Line Arguments

json-trim allows the following command-line flags and options:

| option | alias | usage | description | | :--- | :---: | :--- | :--- | | config | -c | --config <path to configuration file> | Location of the json-trim configuration file, e.g. ./conf/trim.config.js | | destination | -d | --destination <path to target json file> | Output location of the file generated by json-trim, e.g., ./dist/package.json | | env | | --env <environment>[=<sub-env>] | Environment passed to the configuration when it is a function, e.g., dev or prod or prod=dist | | help | -help | --help | Displays usage information | | keeplist | -k | --keeplist <list> <of> <keys> | Space-separated list of json keys to copy, e.g., name version description | | quiet | -q | --quiet | Toggles quiet mode. Will only display errors | | source | -s | --source <path to source json file> | Input location of the file json-trim should copy, e.g., ./package.json | | trimlist | -t | --trimlist <list> <of> <keys> | Space-separated list of json keys to exclude (takes precedence over keeplist) | | verbose | -v | --verbose | Toggles verbose mode | | version | -ver | --version | Gets the current version of json-trim |

Common Options

Note that json-trim has a higher precendence for the arguments you use it with than the options set in your configuration file. For instance, if you pass --env="production" to json-trim on the command-line, and your configuration file uses development, then production will be used.

List all of the commands and flags available on the cli

json-trim --help

Show help for a single flag

json-trim --help <flag>

Execute using a configuration file

json-trim --config ./conf/trim.config.js

This uses the configuration file at ./conf/trim.config.js, and does not override any options.

Execute without using a configuration file

json-trim --source ./package.json --destination ./dist/package.json --trimlist scripts oldscripts devDependencies

This

1. copies ./package.json file to ./dist/package.json,
2. trims the scripts, oldScripts, and devDependencies keys out of the copy, and
3. leaves the original ./package.json unchanged.

Configuration Files

Developers can specify a configuration file to make json-trim usage easier. The config must be an exported javascript function.

If no config file is specified, json-trim will first look for a file in the project root (next to the ./package.json) called ./trim.config.js.

If json-trim finds a config file, it will load that configuration, and then override any options with those specified on the command-line.

NOTE: If a config file is specified on the command line, and json-trim cannot find that config file, then json-trim will fail with an error.

The Configuration Object

When given a json configuration object exported from a config file, json-trim considers the following (case-insensitive) keys:

source

Input location of the file json-trim should copy.

'source': './package.json'

destination

Output location of the file generated by json-trim.

'destination': './dist/package.json'

keeplist [optional]

Case-insensitive String[] array of keys to copy. Will not error if a key is not found.

'keeplist': ['name', 'version', 'description']

trimlist [optional]

Case-insensitive String[] array of keys to exclude (takes precedence over keeplist). Will not error if a key is not found.

'trimlist': ['scripts', 'oldscripts', 'devDependencies']

verbose [optional, default: false]

'verbose': false

quiet [optional, default: false]

'quiet': false

EXAMPLES

The following examples use the structure of the above project (@auturge/maximus). The developer can use json-trim from the command-line (or a scripts entry in the package.json), or by specifying the configuration in a config file.

EXAMPLE: from the Command-Line

Suppose you want the following options:

1. the input file is the ./package.json in the project root (as described above),
2. the output file is ./dist/package.json,
3. remove the scripts, oldScripts, and devDependencies keys.

Your command-line would look like this:

json-trim -s ./package.json -d ./dist/package.json -t scripts oldScripts devDependencies

EXAMPLE: simple config file

Suppose you want the following options:

1. use a config file at the default location, ./trim.config.js,
2. the input file is the ./package.json in the project root (as described above),
3. the output file is ./dist/package.json,
4. remove the scripts, oldScripts, and devDependencies keys, and
5. use the default logging options.

./trim.config.js

const path = require('path');

module.exports = () => {
   return {
        'source': './package.json',
        'destination': './dist/package.json',
        'trimlist': ['oldScripts', 'scripts', 'devDependencies']
    }
}

command-line

json-trim

result (./dist/package.json)

{
  "name": "@auturge/maximus",
  "version": "1.0.0",
  "description": "auturge/maximus - does a thing!",
  "author": "auturge",
  "license": "MIT",
  "bugs": {
    "url": "https://github.com/auturge/maximus/issues"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/auturge/maximus.git"
  },
  "homepage": "https://github.com/auturge/maximus",
  "main": "maximus.js",
  "files": [
    "README.md",
    "CHANGELOG.md",
	...
  ],
  "engines": {
    "node": ">=12.8.1"
  }
}

EXAMPLE: more advanced config file

Suppose you want the following options:

1. your json-trim config file lives in the ./conf/ directory (e.g., at ./conf/trim.config.js),
2. the input file is the ./package.json in the project root (as described above),
3. the output file goes into a specific folder depending on which 'environment' you're building:
   • If you're building in dev mode, the output file should be ./build/dev/package,json
   • If you're building in prod mode, the output file should be ./build/prod/package,json
   • If you're building in dist mode, the output file should be ./dist/package,json
4. keep only the name, version, and description keys, and
5. to see all the little details of what json-trim is doing

./conf/trim.config.js

const path = require('path');

module.exports = (env) => {
    const isProd = env && env['prod'];
    const isDist = isProd && isProd.toLowerCase() === 'dist';

    const SOURCE = './package.json';
    const DESTINATION = isDist
                        ? './dist/package.json' 
                        : './build/{0}/package.json'
                        .replace('{0}', isProd ? 'prod' : 'dev')
    
    const config = {
        'source': path.join(PROJECT_ROOT, SOURCE),
        'destination': path.join(PROJECT_ROOT, DESTINATION),
        'keeplist': ['name', 'version', 'description'],
        'verbose': true
    }
    
    return config;
}

command-line (dev)

json-trim -c ./conf/trim.config.js -env dev

command-line (prod)

json-trim -c ./conf/trim.config.js -env prod

command-line (dist)

json-trim -c ./conf/trim.config.js -env prod=dist

result

{
    "name": "@auturge/maximus",
    "version": "1.0.0",
    "description": "auturge/maximus - does a thing!"
}

Contributing and Internal Documentation

The auturge family welcomes any contributor, small or big. We are happy to elaborate, guide you through the source code and find issues you might want to work on! To get started have a look at our documentation on contributing.

License

Distributed under the MIT license. See LICENSE for more information.