We appreciate any community contributions to this project, whether in the form of issues or Pull Requests.
This document outlines the we'd like you to follow in terms of commit messages and code style.
It also explains what to do in case you want to setup the project locally and run tests.
This project is written in ES2015 and transpiled to ES5 using Babel, to the
dist directory. This should generally only happen at publishing time, or for testing purposes only.
npm install to install all necessary dependencies. When running
npm install locally,
dist is not compiled.
All necessary dependencies are installed under
node_modules and any necessary tools can be accessed via npm scripts. There is no need to install anything globally.
When importing local, in develoment code, via
index.js, this file checks if
dist exists and uses that. Otherwise, it uses the code from
If you have a
dist directory, run
npm run clean.
Axios, one of the main dependencies is vendored. This generally shouldn't matter, but if you'd like to understand why, check SETUP.md
This project uses standard. Install a relevant editor plugin if you'd like.
Everywhere where it isn't applicable, follow a style similar to the existing code.
Commit messages and issues
This project has unit and integration tests. Both of these run on both Node.js and Browser environments.
Both of these test environments are setup to deal with Babel and code transpiling, so there's no need to worry about that
npm testruns all three kinds of tests and generates a coverage report
npm run test:unitruns Node.js unit tests without coverage.
npm run test:coverto run Node.js unit tests with coverage.
npm run test:debugruns babel-node in debug mode (same as running
npm run test:integrationruns the integration tests against the Contentful CDA API. Note: these are tricky to run locally since they currently run against a real contentful org. Focus on unit tests during development as integration tests will be run as part of CI/CD.
npm run test:browser-localruns both the unit and integration tests using Karma against local browsers.
npm run test:ciruns tests in CI
npm run test:browser-remoteruns both the unit and integration tests using Karma against Sauce Labs. This is only usable in the CI environment, as it expects the credentials and connection tunnel to be present.
Code is documented using JSDoc 3, and reference documentation is published automatically with each new version.
npm run docs:watchwatches code directory, and rebuilds documentation when anything changes. Useful for documentation writing and development.
npm run docs:devbuilds code and builds docs afterwards. Used by
npm run docs:watch. Code building is required as the documentation is generated from the unminified ES5 compiled sources, rather than the original ES6 sources. You should then open the generated
out/contentful/index.htmlin your browser.
npm run docs:buildbuilds documentation.
npm run docs:publishbuilds documentation and publishes it to github pages.
npm run cleanremoves any built files
npm run buildbuilds vendored files, node package and browser version
npm run build:distbuilds ES5 sources from ES6 ones
npm run build:standalonebuilds unminified and minified sources for browsers