Professional Trainer
Creating an Open Source JavaScript Library on Github
5 hours, 29 minutes
CC
Course Description
"Participating in open source has been one of the most rewarding experiences of my career." ~Kent C. Dodds. Setup new projects on GitHub, configure npm to publish the project to the npm registry, transpile the source with babel, add unit tests / code coverage and continuous integration (with Travis CI). Run tests automatically and report coverage stats to codecov.io. Automate releases with semantic-release and distribute a browser build with webpack, plus manage the community all in this course on publishing an open source library!
This course and others like it are available as part of our Frontend Masters video subscription.
Preview
CloseCourse Details
Published: December 7, 2016
Topics
Learn Straight from the Experts Who Shape the Modern Web
Your Path to Senior Developer and Beyond
- 200+ In-depth courses
- 18 Learning Paths
- Industry Leading Experts
- Live Interactive Workshops
Table of Contents
Creating an Open Source Library
Section Duration: 30 minutes
Kent Dodds opens his workshop on Writing an Open Source Javascript library with a brief overview of what he’ll be covering and setup requirements. Along with instilling Git, Node, and NPM, Kent recommends creating travis-ci.org and codecov.io accounts.
Before starting an open source project, Kent recommends deciding on an open source license and creating a code of conduct. The license helps outline any restrictions around how the library can be used. While not required, the code of conduct can set behavior expectation for contributors.
In this exercise, Kent walks through creating the CODE_OF_CONDUCT.md, LICENSE, and README.md files. These files are written with Markdown syntax to make it easy to format them for the web. The solution to this exercise is on the FEM/01.0-important branch.
The “npm init” command will initialize a project and create the package.json file. There are a few questions asked by NPM each time the “init” command is run so Kent demonstrates how to update the .npmrc file with pre-populated default values. He then completes the initialization of the star-wars-names project. The code for this example can be found on the FEM/03.0-add-data branch.
Kent sets up the next exercise with a little pseudo code before turning it over to the group. In this exercise you will create the index.js file, install the unique-random-array module, and add the node_modules directory to the .gitignore file.
Kent walks through the solution to the Creating the Library exercise. The code for the solution is located on the FEM/03.1-create-lib branch.
Linting & Testing
Section Duration: 1 hour, 4 minutes
Linting code catches errors, encourages best practices and maintains consistency throughout the project. Kent introduces ESLint and talks about how it compares to JSLint and JSHint. The main advantage of ESLint is that it’s more flexible and pluggable.
In this exercise, Kent installs the eslint Node module. He then walks through the configuration and writing of the library’s first lint script. The solution to this exercise is on the FEM/04.0-linting branch.
Mocha and Chai are unit testing and assertion libraries. In this exercise, Kent demonstrates how to get an initial test runner set up in the library. He creates an index.test.js file which will contain the test scripts and a mocha.opts file for configuring Mocha. The solution to this exercise is on the FEM/05.0-setup-tests branch.
In this exercise, you will write unit tests that cover the starWarsNames.all() and starWarsNames.random() methods. To start, Kent provides some pseudo-code and a few hints. He also talks a little about the dont-break NPM package that verifies changes to one project don’t break dependent projects.
Kent walks through the solution to the Writing Unit Tests exercise. The code for the solution is located on the FEM/05.1-write-tests branch.
Code coverage is the process of monitoring how much code is “covered” by a unit test. Code coverage tools can monitor anything from statements and lines to functions and branches. Target thresholds are set in the configuration and coverage reports are output to the command line.
Kent spends some time demonstrating how to install and configure the nyc Node module to run test coverage reports in the library. After establishing the reports, Kent adds lcov reports which are browser-based and more descriptive. The code for this example is on the FEM/05.2-coverage branch.
Git Hooks, Babel, & Webpack
Section Duration: 1 hour, 54 minutes
Git Hooks are scripts that run either before or after common Git tasks are performed. For example, a script could be configured to run before a project commit. Git Hooks are separate from other project files so in order to share them between projects, Kent introduces the ghooks Node module which makes sharing possible.
In this exercise, Kent walks through how to create a validate script to automatically run the test and linting scripts for the project. The code for this exercise is on the FEM/06.0-validate branch.
Transpiling is the process of converting code from one format to another. In the case of this library, Kent will be transpiling from ES6 syntax to ES5 syntax which has more compatibility. To do this, he will be using the Babel transpiler.
Kent installs and begins configuring Babel. All the transpiled output will be placed in a “dist” directory. After getting some initial configuration in place, Kent demonstrates the transpiling process and talks about a few of Babel’s features.
Kent continues to configure Babel and demonstrates a few additional features. He ignores any test scripts so they are not included in the distribution directory. He also uses the --copy-files flag to copy any non-JavaScript files like the JSON data file into the distribution directory. Finally, he adds the rimraf Node module to remove the “dist” folder each time the build script is run to ensure it’s clean and up-to-date. The code for this example is on the FEM/07.0-transpile-source branch.
The npm pack command creates a zipped bundle of the distribution files as well as some of the other project files. This bundle could then be uploaded to the NPM directory for distribution. After creating this bundle, Kent explores the contents and spends some time configuring the packager so only the necessary files are included.
Now that the library is using ES6 syntax and transpiling with Babel, the test scripts will not run. Kent explains why this is happening and introduces the Babel Register plugin which will help alleviate the problem. He also talks about why the Babel plugin, Istanbul will now be used for code coverage.
In this exercise, Kent adds babel-register and babel-plugin-istanbul to the project. After configuring these to modules, he uses the NODE_ENV to indicate which environment is being used for each script so the correct plugins will be loaded. Since the NODE_ENV variable only works on OSX, Kent adds the cross-env module which allows it to be set cross platform. The solution to this exercise is on the FEM/07.1-transpile-tests branch.
In order for the JavaScript code in this library to be consumable on the web, Kent adds Webpack to the build process. Webpack will be outputting a browser build of the library with the ES6 loader as well as a UMD or Universal Module Definition version making it adaptable with other module loaders.
Kent walks through how to add Webpack along with the Babel and JSON loaders. He then creates the build scripts necessary for building the application with Babel and building the UMD version of the library. All the build scripts are joined with an “npm-run-all” script that will execute them in parallel. The code for this example is on the FEM/08.0-browser-build branch.
In response to an audience question, Kent spends a few minutes talking about peer dependencies. When a library uses peer dependencies, it will specify a range of compatible versions. If one of those versions is already available, it will be used instead of a new version getting imported.
For the remainder of the workshop, Kent will be working from a forked version of the Star Wars Names library. After forking the library, he gives it a new name. Because the name is now different, Kent has to spend a few minutes updating all the places “star-wars-names” was used throughout the source code.
Kent unintentionally forked the Star Wars Names library on the wrong branch. To fix this, he leads the group through moving their projects back to the master branch.
Continuous Integration & Automating Releases
Section Duration: 1 hour, 59 minutes
Travis CI is a continuous integration tool that integrates with Github projects. Kent walks through creating a Travis CI account and connecting it to a Github account. After the account is set up, Kent creates the travis.yml configuration file and explains what each of the properties represent. Code for this exercise can be found on the FEM/09.0-setup-travis branch.
When a library receives pull requests, code coverage of the contributions should continue to be tracked. Kent installs the codecov Node module which will automatically report coverage using the lcov report. Kent then updates the travis.yml configuration file to run the report on the after_success event. After the reports are run Kent demonstrates how to generate badges for the repository README file. Code for this exercise can be found on the FEM/09.1-report-coverage branch.
In order to publish to NPM, first create an account at npmjs.com . Then the “npm publish” command is used to package and upload the library to the NPM registry. After walking through this process, Kent browses a couple of the recently published libraries. The then spends a couple minutes answering audience questions about security and semantic versioning.
Semantic Release is a Node module that will automate package publishing to NPM. It can detect breaking changes, abort releases with insufficient test coverage, and generate change logs from commit messages. Kent spends a few minutes sharing some use cases for Semantic Release.
Before adding automation with the semantic-release Node module, Kent manually versions the library from the command line with NPM. He bumps the version with the “npm major” command and then demonstrates a few other features like patching and deprecating.
In this exercise, Kent begins the process of automating releases for the library project. He installs and configures the semantic-release-cli module, explaining each step along the way. He then looks at all the changes the semantic-release-cli module made to the project.
Kent continues the exercise which adds automated releases to the project. After looking at a few additional configuration options, Kent spends some time talking about commit message formats. Using a consistent message format makes for more clear and understandable change logs. Code for this exercise can be found on the FEM/09.2-auto-release branch.
In this exercise, Kent installs the commitizen, cz-conventional-changelog, and validate-commit-msg Node modules. These modules will not only streamline the authoring of commit messages and change logs, but validate the commit messages are formatted properly. Code for this exercise can be found on the FEM/09.3-commit-message branch.
While waiting for the library to publish, Kent answers a few questions about publishing and security. Once the library is published he navigates to npmjs.com and views the latest version of the library as well as the change log.
Kent shares some slides from a previous presentation he gave about participating in the open source community. He revisits a few of the topics from earlier in the workshop about scoping the project, having a code of conduct, and stresses the importance of automation in the workflow.
Kent continues his discussion about the open source community by sharing his recommendations for creating documentation. He suggests using third-party sites like jsbin.com for providing code examples and explains how to use some Github-provided templates for managing issues.
Contributors are the key to any open source project. Kent concludes his discussion on the open source community by explaining the contributor pipeline. He also shares some advice for encouraging newcomers and those with less open source experience to contribute to projects.
Kent wraps up his workshop by sharing a number of resources about managing and contributing to open source projects.
Learn Straight from the Experts Who Shape the Modern Web
- In-depth Courses
- Industry Leading Experts
- Learning Paths
- Live Interactive Workshops