aegir

AEgir

Automated JavaScript project management.

Migration from v11

There was a large refactor from v11 to v12, so there is some migration needed. All features you need should still be there, but you might need to changes some things.

Custom Config

The aegir section in package.json was not really useful anymore so it is not supported anymore. Any custom configuration you need can be done in .aegir.js.

Pre and Post Hooks

As we are no longer using gulp the previous setup using a custom gulpfile will not work anymore. To setup hooks around your tests you can use a new configuration option hooks in .aegir.js.

// .aegir.js
module.exports = {
  hooks: {
    pre (callback) {
      console.log('I am called before node and browser tests')
      callback()
    },
    post (callback) {
      console.log('I am called after node and browser tests')
      callback()
    }
  }
}

You can also specify hooks.browser and hooks.node if you have a different setup for browser and/or node based tests.

Renamed binaries

aegir is now a single binary with subcommands. You should rename aegir-test to aegir test in your scripts.

Switch from Mocha to Jest

Because the mocha binary was the source of many pains tests in node are now run using Jest. All important features should work as before, but if you were relying on a mocha specific feature it might break now.

Scoped Github Token

The token needed for releases is now looked for after under AEGIR_GHTOKEN.

Project Structure

The project structure when using this is quite strict, to ease replication and configuration overhead.

All source code should be placed under src, with the main entry point being src/index.js.

All test files should be placed under test. Individual test files should end in .spec.js and setup files for the node and the browser should be test/node.js and test/browser.js respectively.

Your package.json should have the following entries.

"main": "src/index.js",
"scripts": {
  "lint": "aegir lint",
  "release": "aegir release",
  "build": "aegir build",
  "test": "aegir test",
  "test:node": "aegir test --target node",
  "test:browser": "aegir test --target browser",
  "coverage": "aegir coverage",
  "coverage-publish": "aegir coverage --upload"
}

Stack Requirements

To bring you its many benefits, aegir requires

• JS written in Standard style
• Tests written in Mocha syntax, executed through Jest in node and karma in the browser.
• Karma for browser tests

Tasks

Linting

Linting uses eslint and standard with some custom rules to enforce some more strictness.

You can run it using

$ aegir lint

Testing

You can run it using

$ aegir test

There are also browser and node specific tasks

$ aegir test --target node
$ aegir test --target browser
$ aegir test --target webworker

Fixtures

Loading fixture files in node and the browser can be painful, that's why aegir provides a method to do this. For it to work you have to put your fixtures in the folder test/fixtures, and then

// test/awesome.spec.js
const loadFixture = require('aegir/fixtures')

const myFixture = loadFixture(__dirname, 'fixtures/largefixture')

If you write a module like interface-ipfs-core which is to be consumed by other modules tests you need to pass in a third parameter such that the server is able to serve the correct files.

For example

// awesome-tests module
const loadFixture = require('aegir/fixtures')

const myFixture = loadFixture(__dirname, 'fixtures/coolfixture', 'awesome-tests')

// tests for module using the awesome-tests
require('awesome-tests')

// .aegir.js file in the module using the awesome-tests module
'use strict'

module.exports = {
  karma: {
    files: [{
      pattern: 'node_modules/awesome-tests/test/fixtures/**/*',
      watched: false,
      served: true,
      included: false
    }]
  }
}

Coverage

You can run it using

$ aegir coverage

To auto publish coverage reports from Travis to Coveralls add this to your .travis.yml file. For more details see node-coveralls.

script:
  - npm run coverage -- -upload

Building

This will build a browser ready version into dist, so after publishing the results will be available under

https://unpkg.com/<module-name>/dist/index.js
https://unpkg.com/<module-name>/dist/index.min.js

You can run it using

$ aegir build

Specifying a custom entry file for Webpack

By default, aegir uses src/index.js as the entry file for Webpack. You can customize which file to use as the entry point by specifying entry field in your user configuration file. To do this, create .aegir.js file in your project's root diretory and add point the entry field to the file Webpack should use as the entry:

module.exports = {
  entry: "src/browser-index.js",
}

Webpack will use the specified file as the entry point and output it to dist/<filename>, eg. dist/browser-index.js.

If .aegir.js file is not present in the project, webpack will use src/index.js as the default entry file.

This requires AEGIR_GHTOKEN to be set.

Releasing

1. Run linting
2. Run tests
3. Build everything
4. Bump the version in package.json
5. Generate a changelog based on the git log
6. Commit the version change & CHANGELOG.md
7. Create a git tag
8. Run git push to origin/master
9. Publish a release to Github releases
10. Publish to npm

# Major release
$ aegir release --type major
# Minor relase
$ aegir release --type minor
# Patch release
$ aegir release

You can also specify a --env for a release, which can be either 'node', 'browser' or 'no-build'.

$ aegir release --node

If no CHANGELOG.md is present, one is generated the first time a release is done.

You can skip all changelog generation and the github release by passing in --no-changelog.

If you want documentation generation you can pass --docs to the release task to build documentation and publish it to the gh-pages branch.

Documentation

You can use aegir-docs to generate documentation. This uses documentation.js with the theme [https://github.com/dignifiedquire/clean-documentation-theme].

To publish the documentation automatically to the gh-pages branch you can run

$ aegir docs --publish

License

MIT

Changelog

12.0.0 (2017-08-25)

Bug Fixes

• gitignore: add all source files (61ee9f4)
• correct jest version (2f47bb8)
• improve package.json config (36d231d)
• release: fix typo (ceae294)
• release: missing pieces (471184f)
• test: always use spec reporter in the browser (5f60764), closes #140
• test: correct browser hooks (4a2c643)
• test: handle various test states (adbfa41)
• test: higher disconnect timeout for karma (0976088)
• webpack: remove deprecated json-loader (b61e7be), closes #137

Features

• browser: use uglify-es instead of uglify-js (668f3ac)
• build: add filesizes to output (7a6f30c)
• coverage: allow for multiple provider publish (a323017)
• deps: update chalk and webpack (f37112c)
• eslint: extract config into its own package (61ad82a)
• lint: allow lint config via eslintrc (dce396c)
• release: include docs generation (07d3554)
• test: better interop and --files option (5468940)
• add update-notifier (fd0a6d8)
• better patch for this.timeout (d4b8c31)
• coverage on travis (261c213)
• implement hooks and fix some bugs (e0f716c)
• make parallel and timeout customizable (4ae78ac)
• reduce default timeout to 40s and enable it in node tests (489fbb3)
• reduce timeout and monkeypatch this.timeout (13894a4)
• support --files on coverage and release (9d58062)
• webpack: include AEGIR_ prefixed env variables (a4adb59)
• use different renderer on ci (c4a9924)
• use jest beta version (bfe2ae2)

<a name="11.0.2"></a>