node package manager


Stop wasting time syncing and updating your project's README and Package Files!


Stop wasting time syncing and updating your project's README and Package Files!

Watch the talk.

Here's some of the things it can do:



  • Install: npm install --global projectz
  • Executable: projectz
  • Editions

    This package is published with the following editions:

    Older environments may need Babel's Polyfill or something similar.

    Once installed locally, you can compile your project using projectz by running the following in your terminal:

    node ./node_modules/.bin/projectz compile

    To make projectz more automatic, we recommended adding the direct command above to your build tool.

    If you don't use a build tool, but do use npm, then you can add the following to your project's package.json file:

      "scripts": {
        "compile": "projectz compile",
        "posttest": "npm run compile"

    The compile script here is runnable via the command npm run-script compile and will compile your project with projectz.

    The posttest script here automatically compiles your project with projectz after your tests have successfully completed, providing you use npm test to run your tests. This is a great place to put projectz as projectz only updates meta documents so won't affect your test, and will always run before a publish.

    If you get a rate limit warning, you will need to add GITHUB_ACCESS_TOKEN (or a GITHUB_CLIENT_ID AND GITHUB_CLIENT_SECRET combination) to your environment. To do this:

    1. Create a personal access token for your computer at:
    2. Projectz needs the readonly/access permissions for repos and users
    3. Generate the token and copy it
    4. Inside your dotfile profile (.bashrc, .zshrc) add export GITHUB_ACCESS_TOKEN="the token value"
    5. Open a new shell, or run export GITHUB_ACCESS_TOKEN="the token value" in your current shell
    6. Run projectz again

    Projectz helps you maintain the following data files:

    • package.json
    • bower.json
    • component.json
    • jquery.json

    It does this by reading them, combining their data in memory, and then outputting the appropriate fields and over-rides for each file.

    Each file can serve as the master meta data file, however you can also define a projectz.cson CSON file that you can use if you'd like to have the benefit of comments, optional commas, multiline strings, etc for your primary meta data file.

    The special fields are as so:

        # Specify your project's human readable name 
        title: "Projectz",
        # Specify your project name 
        name: "projectz",
        # Specify your project's Website URL 
        homepage: "",
        # Specify your project's demo URL 
        # If this is missing, and `homepage` is set, we set it to the `homepage` value 
        demo: "",
        # Specify your project description 
        description: "Stop wasting time syncing and updating your project's README and Package Files!",
        # Specify your project's SPDX License 
        # Uses for parsing 
        license: "MIT",
        # Specify your whether the project can run on the client-side in web browsers 
        # If this is missing, and the component or bower package files exist, then this becomes `true` 
        browsers: true,
        # Specify your project's author details 
        # Can be an array or CSV string 
        author: "2013+ Bevry Pty Ltd <> (",
        # Specify your maintainers 
        maintainers: [
            "Benjamin Lupton ( ("
        # Specify your sponsors 
        sponsors: [
            "Benjamin Lupton ( ("
        # Specify your contributors 
        # This is automatically combined with the contributors from the GitHub Repository API 
        contributors: [
            "Benjamin Lupton ( ("
        # Specify your project's repository details 
        # If this is missing, and `homepage` is a GitHub URL, this determined automatically 
        repository: {
            type: "git",
            url: ""
        # Specify your project's issue tracker 
        # If this is missing, and `repository` is a GitHub repository, this determined automatically 
        bugs: {
            url: ""
        # Specify your project's badges for use in the readme files 
        # Projectz renders badges by sending the `badges` field to the `badges` package. 
        # Below is some sample projectz configuration for this field to render our most common badges. 
        # Even more badge types and configurations are available than just those included below. 
        # Complete details of what is available can be found over at the badges package: 
        badges: {
            "list": [
            "config": {
                "patreonUsername": "bevry",
                "gratipayUsername": "bevry",
                "flattrUsername": "balupton",
                "paypalURL": "",
                "bitcoinURL": "",
                "wishlistURL": "",
                "slackinURL": ""

    Projectz helps you maintain the following readme files:


    It does this by reading them, and replacing comment tags with the appropriate data.

    The following comment tags are supported:

    • <!-- TITLE --> — outputs the package's title field
    • <!-- BADGES --> — outputs the badges you have enabled from your package's badges field
    • <!-- DESCRIPTION --> — outputs the package's description field
    • <!-- INSTALL --> — outputs the package's installation instructions
    • <!-- HISTORY --> — outputs a link to the HISTORY file if it exists, otherwise if it is a Github repository, outputs a link to the releases page
    • <!-- CONTRIBUTE --> — outputs a link to the CONTRIBUTE file if it exists
    • <!-- BACKERS --> — outputs who the backers are for the project, including maintainers, sponsors, funding badges, and contributors
    • <!-- LICENSE --> — outputs a summary of the license information

    As well as these comment tags for updating entire files:

    • <!-- LICENSEFILE --> — outputs the complete license information
    • <!-- BACKERSFILE --> — same as <!-- BACKERS --> but made for an individual file instead

    As an example, here is a a basic file:

    <!-- TITLE -->
    <!-- BADGES -->
    <!-- DESCRIPTION -->
    <!-- INSTALL -->
    ## Usage
    Usage instructions go here
    <!-- HISTORY -->
    <!-- CONTRIBUTE -->
    <!-- BACKERS -->
    <!-- LICENSE -->

    This README is also, expectedly, built with projectz. View its source.


    Discover the release history by heading on over to the file.


    Discover how you can contribute by heading on over to the file.



    These amazing people are maintaining this project:


    No sponsors yet! Will you be the first?


    These amazing people have contributed code to this project:

    Discover how you can contribute by heading on over to the file.


    Unless stated otherwise all works are:

    and licensed under: