panop
panop processes the packages in your Lerna-style monorepo through a set of filters, to produce a single consolidated monorepo information file describing key aspects of each package.
Use cases
The consolidated file produced by panop can be used to build things related to your monorepo project. Examples include:
- A package listing website, such as the AtlasKit Registry
- A file describing key stats about each of your monorepo package versions
Example output
If you have a monorepo with the standard structure:
my-repo/
package.json
packages/
package-one/
...
package-two/
...
Then panop will produce a JSON file with the following structure. Note that the jsStats
and npmInfo
sections are generated by plugins and you create your own plugins!
To see a full example of output data, see the "API data" section linked at the bottom of the AtlasKit Registry.
Plugins
Every package version in your monorepo is passed through a set of plugins. Each plugin is published as a separate panop-plugin-*
npm module.
The available plugins are:
- panop-plugin-pkg-json-info (always enabled)
- panop-plugin-npm-info
- panop-plugin-js-stats
- panop-plugin-css-stats
See below for how to specify plugins via the command line.
Support for repository hosts
Currently panop
only supports repositories which are hosted on Bitbucket Cloud.
Repositories hosted on other services could be supported in the future, pull requests are welcomed!
Installation and usage
npm install -g panoppanop --repo=bitbucket_username/bitbucket_repo --json=registry.json --requestsPerSecond=2 --plugins=pkg-json-info,npm-info # your registry.json file will be saved
Available arguments:
repo
: the Bitbucket repository you want to inspect (required, format isusername/repo
)json
: path where your consolidated file will be saved to (required)plugins
: comma-separated list of plugins (optional, default ispkg-json-info
)requestsPerSecond
: the maximum number of Bitbucket API requests which will be made per second (optional, default 20)mergeData
: path to a previously-exported panop JSON file, for faster incremental builds. NOTE: make sure you specify the same plugins both times.pkgScope
: name of a single package to process. Useful for debugging.
If your repo
argument is a private repository, make sure you set your BITBUCKET_USER
and BITBUCKET_PASS
environment variables before running panop
.
Development
npm install -g yarn # if you don't have yarn already git clone git@bitbucket.org:atlassian/panop.gitcd panopyarn install # install commitizen npm install -g commitizen
Then instead of using git commit
, do git cz
.
Tests
To run the tests locally, simply use npm run test
. If you are developing and want to run tests on each file change, use npm run test/watch
.
Each commit to the central panop repo on Bitbucket triggers the standard test suite as well as an end-to-end integration test. You can view the status of a branch's tests by the Branches page.
The docker image used for Bitbucket Pipelines can be rebuild and republished using docker build -t "atlassianlabs/panop:latest" . && docker push "atlassianlabs/panop:latest"
Contributors
Pull requests, issues and comments welcome. For pull requests:
- Add tests for new features and bug fixes
- Follow the existing style
- Separate unrelated changes into multiple pull requests
See the existing issues for things to start contributing.
For bigger changes, make sure you start a discussion first by creating an issue and explaining the intended change.
Atlassian requires contributors to sign a Contributor License Agreement, known as a CLA. This serves as a record stating that the contributor is entitled to contribute the code/documentation/translation to the project and is willing to have it used in distributions and derivative works (or is willing to transfer ownership).
Prior to accepting your contributions we ask that you please follow the appropriate link below to digitally sign the CLA. The Corporate CLA is for those who are contributing as a member of an organization and the individual CLA is for those contributing as an individual.
License
Copyright (c) 2016 Atlassian and others. Apache 2.0 licensed, see LICENSE.txt file.