{"id":21186613,"url":"https://github.com/fetchte/js-library-setup-guide","last_synced_at":"2025-03-14T20:18:17.197Z","repository":{"id":89445588,"uuid":"94252204","full_name":"fetchTe/js-library-setup-guide","owner":"fetchTe","description":"JavaScript/NPM Library Setup Guide and Boilerplate Script","archived":false,"fork":false,"pushed_at":"2017-10-05T21:37:31.000Z","size":772,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-21T12:48:39.485Z","etag":null,"topics":["boilerplate","library","npm"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fetchTe.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-06-13T19:58:07.000Z","updated_at":"2017-10-04T03:07:47.000Z","dependencies_parsed_at":null,"dependency_job_id":"98852199-90d9-4b51-9b2b-e92bb7e07ac8","html_url":"https://github.com/fetchTe/js-library-setup-guide","commit_stats":null,"previous_names":["fetchte/js-library-setup-guide"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fetchTe%2Fjs-library-setup-guide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fetchTe%2Fjs-library-setup-guide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fetchTe%2Fjs-library-setup-guide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fetchTe%2Fjs-library-setup-guide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fetchTe","download_url":"https://codeload.github.com/fetchTe/js-library-setup-guide/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243639557,"owners_count":20323511,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["boilerplate","library","npm"],"created_at":"2024-11-20T18:24:48.032Z","updated_at":"2025-03-14T20:18:17.175Z","avatar_url":"https://github.com/fetchTe.png","language":"JavaScript","readme":"# JavaScript/NPM Library Setup Guide and Boilerplate Script\n[![wercker status](https://app.wercker.com/status/6b74cb8e232cae0b35d3b27bf034d9fc/s/master \"wercker status\")](https://app.wercker.com/project/byKey/6b74cb8e232cae0b35d3b27bf034d9fc)\n\n## Description\n\nYou know what confused me the most when I first started developing JavaScript libraries? The how's, why's, and what's of setting up the dot-files, build/auxiliary tools, and configuring all the separate pieces to work together. I looked high and low for a guide like this, but alas my search was fruitless, so I took the time to create one. Hopefully this guide and automatic setup will help you setup your project in a jiffy to you don't have to spend all the time I did.\n\nThe current structure and setup is a culmination of three years of trial and error. And I can say with confidence that it's a pretty good template to start with. It also includes useful auxiliary tools to help manage and support your library. Plus there's a script that will set everything up for you automatically. Although, at the same time, I break down each component in detail as to what it does and how to use it below.\n\nIf you want to view some example repositories that utilize this project structure you can checkout any repository in [ctr-lang](https://github.com/ctr-lang).\n\n---\n\n## Table of Contents\n\n+ [Initial Setup](#initial-setup)\n+ [Commands](#commands)\n+ [Root Dot-Files](#root-dot-files)\n+ [Folders](#folders)\n+ [Pull Requests](#pull-requests)\n+ [How to Release a New Version](#how-to-release-a-new-version)\n+ [Tag and Publish](#tag-and-publish)\n+ [Auxiliary Tools](#auxiliary-tools)\n\n\n---\n\n## Initial Setup\n\nEither you can set things up manually or automatically. I recommend the automatic route in which all you need to do is run the following command:\n\n```bash\n   npm start\n```\n\nYou'll be prompted to answer a series of questions and based on your answers it will configure the files and their contents for you.\n\n---\n\n## Commands\n\n+ `npm run test` -\u003e Runs the tests in the `__test__` directory\n+ `npm run dev` -\u003e For development of your library\n+ `npm run build` -\u003e For bulding your library for publish/release\n+ `release:major` -\u003e Preps for a major release. Refer to the [\"How to Release a New Version\"]((#how-to-release-a-new-version)) section below\n+ `release:minor` -\u003e Preps for a minor release. Refer to the [\"How to Release a New Version\"]((#how-to-release-a-new-version)) section below\n+ `release:patch` -\u003e Preps for a patch release. Refer to the [\"How to Release a New Version\"]((#how-to-release-a-new-version)) section below\n\n---\n\n## Root Dot-Files\n\n### `.babelrc`\n\nThis file is the run-time configuration for the [babel-loader](https://github.com/babel/babel-loader) which is used in conjunction with [webpack](https://webpack.js.org). Essentially, it tells [Babel](http://babeljs.io/) how to compile your JavaScript, although, we utilize the [babel-preset-env](https://github.com/babel/babel-preset-env) which:\n\n\u003e Automatically determines the Babel plugins and polyfills you need based on your supported environments.\n\nHere's a example configuration that is also the default configuration. It targets node version `4` and the `last 2 versions` of all major browsers.\n\n```json\n{\n  \"presets\": [\n    [\"env\", {\n      \"targets\": {\n        \"node\": \"4\",\n        \"browsers\": [\"last 2 versions\"]\n      }\n    }]\n  ]\n}\n```\n\n\nTo determine your environment and the corresponding support for ECMAScript features you can use the [`compat-table`](https://kangax.github.io/compat-table/es6/). There's also plethora of options and configures that you can read about in the [repository](https://github.com/babel/babel-preset-env). Keep in mind that you **must** include `import 'babel-polyfill';` otherwise [babel-preset-env](https://github.com/babel/babel-preset-env) not include any polyfills.\n\n\n### `.bumpedrc`\n\nThis file is the run-time configuration for [Bumped](https://www.npmjs.com/package/bumped) which: \n\n\u003e Is a release system that makes it easy to perform actions before and after releasing a new version of your software.\n\nThe rule of thumb in all software development is to track your development and changes and release using a schema such as [Semantic Versioning](http://semver.org/). I'll run through a quick example as to why this is important. Let's say you make some major changes to your API and these changes create breaking changes. That is changes that will break a users setup if they upgrade without making the correct changes to their code/setup.\n\nAfter you make these changes you will need to release a new version of your library both to Github and NPM. And once you do so other developers will come visit your repository to see what changed and what they need to change in order to upgrade to the next version. If you don't do this users of your library will upgrade unknowingly and their build will break and they won't be happy. Admittedly, this task of business can be a pain in the butt, but it’s a MUST and Bumped makes this process suck a bit less.\n\n\n### `.cz-config.js`\n\nThis file is for setting up a customizable [commitizen](http://commitizen.github.io/cz-cli/) cli. If you're unfamiliar with commitizen it provides:\n\n\u003e Simple commit conventions for internet citizens.\n\nUsing commitizen depends largely on personal preference and during initial/early development I typically don't use it. However, once you release your project out into the wild it can be advantageous to have commit conventions not for you, but for others. In addition, commitizen is almost mandatory if you wish to use Zapper and it's commit message tests.\n\n\n### `.env-cmdrc`\n\nThis file set environment variables for the npm scripts, [env-cmd](https://www.npmjs.com/package/env-cmd) is:\n\n\u003e A simple node program for executing commands using an environment from an env file.\n\nUsing environment variables makes your life ten times easier and env-cmdrc makes working with them a breeze in the park.\n\n### `.editorconfig`\n\nThis file set the rules for [EditorConfig](http://editorconfig.org/) which helps:\n\n\u003e Developers define and maintain consistent coding styles between different editors and IDEs.\n\nFor example, the current `.editorconfig` stipulates that there should always be a extra space at the end of every files. And this extra space will be added for you automatically if you forget to do so upon saving your file. There's a whole list of rules you can employ and you can specify separate rules for different file types, but for the most part the current `.editorconfig` is pretty bare bones.\n\n\n### `.eslintrc.js`\n\nThis file is for the rule configuration of [ESLint](http://eslint.org/) which is a:\n\n\u003e Pluggable linting utility for JavaScript and JSX.\n\nIf you're unfamiliar with linters you are missing out in life. I'll give you the skinny on linters. They're tools that set style rules for your code like always using semicolons as well as catch common errors. The current `.eslintrc.js` is highly configurable and all the defined rules have comments next to them to explain what they do. Alternatively, you could use a big-name style guide like [Airbnb](http://airbnb.io/javascript/), but it's completely up to you.\n\nI should note, some people use linting tests that lint all the files to make sure there are no \"linting\" errors, although, I believe this is actually a anti-pattern that causes more harm than good. In my mind you should always _try_ to abide by the rules but never conform to the rules just for the sake of rules.\n\n\n### `.gitattributes`\n\nThe `.gitattributes` file allows you to:\n\n\u003e Ensure consistent git settings across machines.\n\nMeh, I have mixed feelings about this file since it does not do much for me personally but I'll let you decide if you want to include it in your project or not. You can read more about it [here](https://git-scm.com/docs/gitattributes).\n\n\n### `.gitignore`\n\nThe `.gitignore` file allows you to tell git to:\n\n\u003e Intentionally untracked files.\n\nThis is where you would specify files/folders that you don't want git to track. Be it private files, API keys, etc, although you can read more about it [here](https://git-scm.com/docs/gitignore). The current `.gitignore` file has a whole gambit of default settings that should cover most use cases.\n\n\n### `.npmignore`\n\nThe `.npmignore` file allows you to tell NPM to keep:\n\n\u003e Files out of your package.\n\nWhen you publish your package to NPM you don't want to or need to publish everything and this is what the `.npmignore` file is for. It's the same things as `.gitignore` file, but just for NPM. You can read more about it [here](https://docs.npmjs.com/misc/developers), and like the `.gitignore` file, the `.npmignore` file has a whole gambit of default setting that should cover most use cases.\n\n\n### `.zappr.yaml`\n\nThe `.zappr.yaml` file sets the configuration setting for Zappr which is a:\n\n\u003e Github integration built to enhance your project workflow.\n\nZappr has some fantastic documentation that you can/should read [here](https://zappr.readthedocs.io/en/latest/). But in short it helps with, code review, compliance, and various bottlenecks.\n\n\n\n---\n\n## Folders\n\n\n### `.github/`\n\nThe `.github` folder contains templates for both pull requests and issues. You can read more about the `.github` templates files [here](https://help.github.com/articles/creating-a-pull-request-template-for-your-repository/). But the gist is they help set a uniformity for pull requests and issues.\n\n### `__scripts__/`\n\nThe `__scripts__` folder contains various build scripts that are typically initialized by a `package.json` command. For example, let's say you need to make alterations to various HTML files post build like removing comments, minifying, class additions, etc, you would create said scripts in the `__scripts__` folder. Conversely, you may have custom development or setup scripts — this is the place where you should place them. So it should be obvious that the automated scripts for this project resides in the `__scripts__` folder.\n\n\n### `__tests__/`\n\nShould be self-explanatory. This is where you place all your tests. The `__tests__` setup defaults to [mocha](https://mochajs.org/) and [Should.js](https://shouldjs.github.io/) but this can be easily changed.\n\n\n### `dist/`\n\nShort for distribution. This is the build folder for webpack. It will output all builds of your project whether that be node, browser, browser-minified, or all three. Essentially these are the file(s) the end user will use.\n\n\n### `lib/`\n\nShort for library. This is the development folder in which you will build your library. During development webpack will watch this folder and recompile your build into the `dist` folder on every alteration/change.\n\n\n\n---\n\n## Pull Requests\n\nNOTE: The following directions are the same directions that are in the `CHANGELOG.md` file just with `\u003cXXX\u003e` placeholders.\n\n1. [Fork](https://help.github.com/fork-a-repo/) the repository.\n\n   ```bash\n   git clone https://github.com/\u003cyour-username\u003e/\u003cgitPROJECTNAME\u003e.git\n   cd \u003cgitPROJECTNAME\u003e\n   git remote add upstream https://github.com/\u003cgitUSERNAME\u003e/\u003cgitPROJECTNAME\u003e.git\n   ```\n\n2. Link `\u003cgitPROJECTNAME\u003e`, to symlink the package folder during development.\n\n   ```bash\n   yarn run link\n   ```\n\n3. Install the dependencies. Make sure you have [yarn](https://yarnpkg.com) [installed](https://yarnpkg.com/en/docs/install).\n\n   ```bash\n   yarn install\n   ```\n\n4. Create a new branch to contain your feature, change, or fix.\n\n   ```bash\n   git checkout -b \u003ctopic-branch-name\u003e\n   ```\n\n5. Commit your changes in logical chunks.\n    + To keep commits uniform, this project uses [commitizen](http://commitizen.github.io/cz-cli/), but don't worry if you've never heard about commitizen or don't know how to use it. Everything is pre-configured and ready for you to rock 'n' roll out of the box. Just follow these simple steps:\n        1. Make your update/change/fix\n        2. Add your changes `git add .`\n        3. Run: `npm run commit` - An interactive command prompt will appear and lead you step-by-step through the whole process. It's easy peasy lemon squeezy so don't worry about a thing.\n    + If commitizen does not work or for some extraneous reason you wish not to use it your commit must follow the [angular commit](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#-git-commit-guidelines) format: `\u003ctype\u003e(\u003cscope\u003e): \u003csubject\u003e`. Otherwise, your pull request will fail during approval, but it’s highly encouraged you use `npm run commit` to make everyone's life just a bit easier.\n\n6. Test changes and/or write test(s) to validate feature, change, or fix.\n\n   ```bash\n   npm run test\n   ```\n\n7. Locally merge (or rebase) the upstream development branch into your topic branch.\n\n   ```bash\n   git pull [--rebase] upstream master\n   ```\n\n8. Push your topic branch up to your fork.\n\n   ```bash\n   git push origin \u003ctopic-branch-name\u003e\n   ```\n\n9. [Open a Pull Request](https://help.github.com/articles/using-pull-requests/) with a clear title and description against the `master` branch. Suggestions, changes, or improvements may be required for your changes to be merged, but small pull requests should be accepted quickly. Ideally, your pull request meets the four pillars of quality:\n    1. Update/change/fix has test(s)\n    2. Follows the existing code style\n    3. Has decent commit message(s)\n    4. Commit, and code comes with a smile\n\n\n\n---\n\n## How to Release a New Version\n\n__Preconfig/Setup__\n\nBefore you release a new version make sure you are familiar with [Semantic Versioning](http://semver.org/) so you know what type of release you need to make. Once your familiar with Semantic Versioning you will want to create a new issue titled `Release: \u003cX.X.X\u003e` and create a new corresponding branch that references the issue number such as `pr-#\u003cRELEASE-ISSUE-NUMBER\u003e`. \n\n__Bumped Command__\n\nOnce you're on the new branch you will want to run one of the following commands that corresponds with the release version.\n\n```bash\n   # X.0.0\n   yarn run release:major\n   # 0.X.0\n   yarn run release:minor\n   # 0.0.X\n   yarn run release:patch\n```\n\nThe command does the following:\n\n1. Runs your changes against your tests via `npm test`\n2. Bumps the `package.json` version\n3. Adds and commits `package.json`\n   + Commit message: `release(\u003cX.X.X\u003e): Release: \u003cX.X.X\u003e`\n4. Logs the changes (the commit history) to `CHANGELOG.md`\n5. Adds and amends the previous commit with the `CHANGELOG.md` with the same commit message\n\n__Post-Bumped Alterations__\n\nAfter the Bumped command finishes you'll want remove any fruitless commits from the `CHANGELOG.md`. Alternatively, you can keep it how it is, but typically I remove commits that are not worthy like a commit that `\"Fixes sentence fragment\"`. If you do make any changes you will need to amend those changes.\n\n```bash\n   git add CHANGELOG.md\n   # Commits the changes but does not change the commit message\n   git commit --amend --no-edit\n```\n\n__Push \u0026 Merge__\n\nAt this point you need to push the release branch to the repository.\n\n```bash\n   # Pushes the top of the current branch\n   git push origin HEAD\n```\n\n1. Go to the repository on Github\n2. You should see a yellow prompt box with a green button labeled \"Compare \u0026 Pull Request\". Click that button and it will take you to a new pull request page.\n3. The title should be pre-filled with the commit message, but you will want to use the textarea to make a commit message that closes the release issue.\n    * In the textarea leave a comment that says: `CLOSES #\u003cRELEASE-ISSUE-NUMBER\u003e`\n    * The reason you do this is because Github then automatically attaches and close issues the issue otherwise you must do this yourself. And if you want to learn more about this functionality you can read about it [here](https://help.github.com/articles/closing-issues-via-commit-messages/). \n4. Now click the green button labeled \"Create pull request\" which will take you to the finial pull request page.\n5. Once your pull request passes any and all checks you have in place such as testing in the cloud you will want to click the green button labeled \"Merge pull request\".\n6. Boom, done! Now head back to your code.\n\n\n__Tag and Publish__\n\nAfter merging the release branch on Github you want to  checkout the `master` branch and update the local `master` branch with the merged changes:\n\n```bash\n   git checkout master\n   git pull\n```\n\nNow you want to \"Tag\" your release. You can do this using the command line, but again, I recommend you use Github. On Github you should see right below the repository description a link/text that is labeled \"releases\" which is next to \"branches\" on the left and \"contributors\" on the right. Click the \"releases\" label and it should bring you to a new page and you will want to click the button labeled \"Create a new release\". This again will bring you to a new page to draft your release. The following is the input labels and their respective outputs:\n\n+ Tag version: `\u003cX.X.X\u003e`\n+ Release title: `\u003cX.X.X\u003e` (some people use descriptor titles I don't)\n+ Describe this release: Copy the release text from the `CHANGELOG.md` file and paste it here.\n+ Click the green \"Publish release\" button and then your done\n\nThe finial step is to update the NPM package that is if you have your library on NPM. To do so simply run:\n\n```bash\n   npm publish\n```\n\n---\n\n## Auxiliary Tools\n\nAuxiliary tools are tools that integrate into Github, but are provided by an outside service. All these tools help you better organize, manage, and streamline your project, and while these tools are completely optional I do recommend them.\n\n+ [Waffle.io](https://waffle.io/)\n    * Description: A [kanban board](https://en.wikipedia.org/wiki/Kanban_board) for smart and simple project management. It automatically tracks your work on various issues and pull requests.\n    * Setup:\n        1. Go to [Waffle.io](https://waffle.io/) and sign-up\n        2. Link your Github account\n        3. Link your Github project\n+ [Zappr](https://zappr.opensource.zalan.do)\n    * Description: A bot that enforces guidelines for your GitHub repository and automatically checks pull requests before they are merged.\n    * Setup:\n        1. Go to [Zappr](https://zappr.opensource.zalan.do/login) and sign-up\n        2. Link your Github account\n        3. Link your Github project\n+ [CLA Assistant](https://cla-assistant.io/)\n    * Description: A bot that ensures contributors sign a CLA for the work they contribute. Typically this is only needed if you're working on a large project that you may want to monetize or change the license in the future. The jury is quite literally out on CLA's, but in my mind it's better to be safe then sorry. Plus  the CLA assistant makes signing a CLA a trivial matter.\n    * Setup:\n        1. Go to [CLA Assistant](https://cla-assistant.io/) and sign-up\n        2. Draft a CLA, you can find templates online or use something similar to Githubs [CLA](https://cla.github.com/)\n        3. Select the project/organization\n        4. That's it. It creates the necessary web-hooks in Github and you are set.\n\n---\n\nBest, te\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffetchte%2Fjs-library-setup-guide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffetchte%2Fjs-library-setup-guide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffetchte%2Fjs-library-setup-guide/lists"}