Skip to content

Latest commit

 

History

History
1159 lines (901 loc) · 35.5 KB

TOOLING.md

File metadata and controls

1159 lines (901 loc) · 35.5 KB

Tooling

This document contains resources to help you in both the tooling and development of the tw-themes project.

At a Glance

NPM Scripts

This section provides a summary of the available NPM Scripts (organized by task):

DEVELOPMENT
===========
JS:
test:watch ..... run test suite, continuously watching for module changes

DOCS:
docs:build   ... manually build the docs (into the _book/ dir)
                 1. start an internal web server pointing to _book/ dir
                 2. manually re-execute docs:build whenever docs/ change


TESTING
=======
test ........... run test suite, one time
test:watch ..... run test suite, continuously watching for module changes


DOCS             NOTE: we PUBLISH our docs
====
docs:build   ... manually build the docs (into the _book/ dir)
                 - NOTE: this build is executed as the first step in docs:publish
                 - FOR DOCS DEVELOPMENT:
                   1. start an internal web server pointing to _book/ dir
                   2. manually re-execute docs:build whenever docs/ change
                 - this is MUCH PREFERRED over docs:serve
                   * it is MUCH FASTER!
                   * docs:serve is very antiquated (a dead project)
                     * it is extremely slow
                     * it constantly stops when any file changes
                                    
docs:publish ... publish the latest docs to https://tw-themes.js.org/
                 NOTE: this script FIRST builds the docs from scratch
                       ... via predocs:publish

docs:clean   ... clean machine-generated docs/ directory

                 >>> ANTIQUATED (see notes on docs:build)
docs:serve ..... launch docs server, continuously watching for docs changes
                 NOTE: adding `--log=debug --debug` to this npm script CAN BE USEFUL


BUNDLE/DEPLOY    NOTE: we DEPLOY our bundled library to NPM
=============
lib:build ...... build library bundle in lib/ directory
                 NOTE: This script FIRST insures all unit tests pass
                       ... via prelib:build

lib:clean ...... clean machine-generated lib/ directory

                 NOTE: to deploy library:
                 $ npm publish
                   ... will auto build lib/ directory
                       via: "prepare": "npm run lib:build" 
                   ... and deploy to NPM


MISC
====
clean .......... AI: cleans ALL machine-generated directories

Dependencies

This section provides some insight regarding the various dependencies found in tw-themes.

The dependency list can become quite large for a mature project. In looking at package.json, the inevitable questions are:

  • What is this dependency

  • Why is it needed

  • Is it a dependency for project tooling or application code?

The following table itemizes the tw-themes dependencies, referencing when/where they were introduced/configured.

Dependency Type Usage Refer To
@babel/cli TOOLING Lib Packaging Setup Lib Packaging
@babel/core TOOLING Lib Packaging
Jest Testing		 Setup Lib Packaging
Setup Unit Testing
@babel/preset-env TOOLING Lib Packaging
Jest Testing		 Setup Lib Packaging
Setup Unit Testing
babel-jest TOOLING Jest Testing Setup Unit Testing
gh-pages TOOLING Docs Deployment Setup Docs Tooling
gitbook-cli TOOLING Docs Generation Setup Docs Tooling
jest TOOLING Jest Testing Framework Setup Unit Testing
rimraf TOOLING Various NPM Clean Scripts Setup Docs Tooling
tailwindcss TOOLING
APP		 our peerDependency
(what tw-themes is built on)		 Initialize NPM Project
and app code: src/...

Project Resources

Wondering what some of the top-level file resources are? Here is a summary:

tw-themes/
  .git/ ................ our local git repo
  .gitignore ........... git repo exclusions (typically machine generated)
  _book/ ............... machine generated docs (output of GitBook)  see: "Setup Docs Tooling"
  babel.config.js ...... babel configuration used by:
                         - library packaging (see: "Setup Lib Packaging")
                         - jest (see: "Setup Unit Testing")
  book.json ............ GitBook configuration see: "Setup Docs Tooling"
  docs/ ................ master source of GitBook project docs  see: "Setup Docs Tooling"
    *.md ............... various Markdown files making up our docs
  jest.config.js ....... jest unit testing configuration see: "Setup Unit Testing"
  LICENSE.md ........... our MIT License
  node_modules/ ........ install location of dependent packages (maintained by npm)
  package.json ......... project meta data with dependencies
  package-lock.json .... exhaustive dependency list with installed "locked" versions (maintained by npm)
  README.md ............ basic project docs
  src/ ................. the app source code
    index.js ........... promotes all tw-themes PUBLIC API
    snip snip .......... many more!
  TOOLING.md ........... this document :-)

Project Setup

This section chronicles the original setup of the tw-themes project.

If you are forking this project, this detail is unnecessary, because you simply npm install and then commence your development.

With that said, this section provides valuable insight on how the project was originally setup and configured, and can be used in other projects (where you are starting from scratch)!

NOTE: These sections roughly represent the chronology of when they were carried out, however in some cases the order can be changed.

Sub Sections:

Setup GitHub Project

There are many ways of initiating a new GitHub project. I'll leave the details to you :-)

At the end of this process you should have:

  • A new GitHub project
  • A local git repository (for your development)
  • Impacted Files: 
      tw-themes/
    .git/ ................ our local git repo
    .gitignore ........... git repo exclusions (typically machine generated)
    LICENSE.md............ MIT License
    README.md ............ basic project docs

My personal notes are "hidden" (in comment form) in this doc ...

Initialize NPM Project

This task will initialize the project as an NPM project.

At the end of this process you should have:

  • tw-themes initialized as an NPM project, with it's tailwindcss peerDependency.

  • Impacted Dependencies:

    tailwindcss ... our peerDependency (what tw-themes is built on)

  • Impacted Files:

    tw-themes/
  .gitignore ........... modified as needed
  node_modules/ ........ install location of dependent packages (maintained by npm)
  package.json ......... project meta data with dependencies
  package-lock.json .... exhaustive dependency list with installed "locked" versions (maintained by npm)

Summary:

  1. Create package.json file at project root, with following the characteristics (this contains our tailwindcss peerDependency):

    {
  "name": "tw-themes",
  "version": "0.1.0",
  "description": "powerful tailwind color themes (dynamically selectable at run-time)",
  "homepage": "https://tw-themes.js.org/",
  "repository": {
    "type": "git",
    "url": "https://github.com/KevinAst/tw-themes.git"
  },
  "keywords": [
    "tailwind",
    "themes",
    "theme",
    "dark",
    "dark-mode",
    "colors",
    "web",
    "utility",
    "geeku",
    "astx"
  ],
  "author": "Kevin J. Bridges <[email protected]> (https://github.com/KevinAst)",
  "license": "MIT",
  "scripts": {
    "L8TR": "L8TR"
  },
  "devDependencies": {
    "tailwindcss": ">=2.0.0"
  },
  "peerDependencies": {
    "tailwindcss": ">=2.0.0"
  }
}

  2. Initialize Node/NPM:

    $ cd c:/dev/tw-themes
$ npm install

  3. Update .gitignore with following:

    # node dependencies (defined via "npm install")
/node_modules/

# not really interested in package-lock.json in repo
/package-lock.json

... snip snip

My personal Detailed Notes are "hidden" (in comment form) in this doc ...

Setup Unit Testing

tw-themes uses Jest as it's unit testing framework.

Links:

At the end of this process you should have:

  • The ability to use Jest in running the test suite.

  • Impacted Dependencies:

    @babel/core
@babel/preset-env
babel-jest
jest

  • Impacted Files:

    tw-themes/
  babel.config.js
  jest.config.js

Installation Details:

  • Install required dependencies (Jest and Babel).

    NOTE: Some of these dependencies overlap with other setup (Install only what is missing):

    $ npm install --save-dev @babel/core @babel/preset-env jest babel-jest
  + [email protected]
  + [email protected]
  + @babel/[email protected]
  + @babel/[email protected]
    added 576 packages from 365 contributors and audited 658 packages in 37.522s

  • Configure Jest/Babel by adding two files (in project root):

    • jest.config.js: 
      // configuration of jest unit tests
module.exports = {
  transform: {
    "^.+\\.js$": "babel-jest"
  },
  moduleFileExtensions: ["js"],

  // KJB: other UNNEEDED (I think)
  // testPathIgnorePatterns: ["node_modules"],
  // bail: false,
  // verbose: true,
  // transformIgnorePatterns: ["node_modules"],
};
    • babel.config.js: 
      // babel needed for jest unit tests :-(
module.exports = {
  presets: [
    [
      "@babel/preset-env",
      {
        targets: {
          node: "current"
        }
      }
    ]
  ]
};

  • Setup the Testing NPM Scripts: package.json:

    ... snip snip

"scripts": {
  ...
  "test":       "jest src",
  "test:watch": "npm run test -- --watch"
},

... snip snip

Setup Docs Tooling

tw-themes promotes it's documentation through GitHub Pages, using GitBook, which is a Markdown based solution. This configuration setup is patterned after the following article (minus the JSDoc): Integrating GitBook with JSDoc to Document Your Open Source Project.

At the end of this process you should have:

  • Documentation setup through Markdown files, deployable to GitHub Pages.

  • Impacted Dependencies:

    gh-pages
gitbook-cli
rimraf

  • Impacted Files:

    package.json ...... enhance docs dependencies -and- docs scripts
book.json ......... GitBook configuration
docs/ ............. master source of GitBook project docs
  toc.md .......... the summary TOC (seen in the left nav)
  intro.md ........ the Guide Introduction
  *.md ............ various Markdown files making up our docs
  sectionN/ ....... optional docs dirs (as required)
    *.md
  styles/
    website.css ... gitbook style overrides
_book/ ............ machine generated docs (output of GitBook)
  *.html
  *.js
  *.css

Installation Details:

  1. Install the GitBook command-line interface

    $ npm install --save-dev gitbook-cli
  + [email protected]
    added 577 packages from 672 contributors and audited 1234 packages in 32.693s

    KJB: Yikes: this is the same version installed 3 years ago (in feature-u).

    It has 10K downloads / week, but was last published 4 years ago ... hmmm

  2. Define following doc-related project files

    NOTE: To find the installed gitbook version (referenced in book.json below):

    $ npx gitbook ls
  GitBook Versions Installed:
  * 3.2.2
    2.5.2

    book.json (GitBook configuration)
=========
  {
    "gitbook":     "3.2.2",
    "root":        "./docs",
    "title":       "tw-themes",
    "description": "powerful tailwind color themes (dynamically selectable at run-time)",
    "author":      "Kevin J. Bridges <[email protected]> (https://github.com/KevinAst)",
    "structure": { 
      "readme":  "intro.md",
      "summary": "toc.md" 
    }
  }

docs/

  toc.md (defines the left-nav)
  ======
    # Table of content 
    
    ### tw-themes (0.1.0)
    * [Getting Started](start.md)
    
    ----

  intro.md (docs introduction)
  ========
    # tw-themes

    **tw-themes** is a tailwindcss utility that facilitates _**dynamic
    color themes that are selectable at run-time**_.

  start.md (our getting started)
  ========
    # Getting Started
    This is the **Getting Started** section.
    Here are some references to the [Introduction](intro.md)
    and [API](api.md).

  3. Install gh-pages (used in npm scripts below)

    $ npm install --save-dev gh-pages
  + [email protected]
    added 28 packages from 10 contributors and audited 1262 packages in 10.237s

  4. Install rimraf (used in npm scripts below)

    $ npm install --save-dev rimraf
  + [email protected]
    updated 1 package and audited 1263 packages in 7.012s

  5. Define the following docs-related NPM scripts:

    package.json:

    ... snip snip
"scripts": {
  ...
  "docs:build":            "gitbook build",
  "docs:serve":            "gitbook serve",
  "predocs:publish":       "npm run docs:build",
  "docs:publish":          "gh-pages --dist _book",
  "docs:gitbook:help":     "gitbook help",
  "docs:clean":            "rimraf _book"
  ...
},
... snip snip

  6. Prep/Initialize gitbook plugins. This step is needed whenever you add gitbook plugins via book.json. As an example the toolbar plugin (mentioned below).

    $ npx gitbook install
      info: nothing to install!
            KJB: This command only needs to be run when gitbook plugins
                 are added to book.json

  7. Serve up docs to test our setup

    $ npm run docs:serve

    And browse: http://localhost:4000/

    Resolve Issues

    - It appears that gitbook-cli is so old that it has issues running
  in a modern node/npm.

  Starting to question is gitbook is the best option for documentation
  ... at least in future projects

- When running either "docs:build"/"docs:serve" receive follow error:
  $ npx gitbook build
    C:\dev\tw-themes\node_modules\npm\node_modules\graceful-fs\polyfills.js:287
          if (cb) cb.apply(this, arguments)
                     ^
    TypeError: cb.apply is not a function
        at C:\dev\tw-themes\node_modules\npm\node_modules\graceful-fs\polyfills.js:287:18
        at FSReqCallback.oncomplete (fs.js:184:5)

  * found several mentions of this:

    1. Gitbook-cli install error TypeError: cb.apply is not a function inside graceful-fs
       ... https://stackoverflow.com/questions/64211386/gitbook-cli-install-error-typeerror-cb-apply-is-not-a-function-inside-graceful
       * they talk about gitbook-cli working in node v12 and NOT in node v14
       * they install a newer version of graceful-fs@latest IN gitbook-cli
         $ cd /usr/local/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/
         $ npm install graceful-fs@latest --save

    2. How I fixed a "cb.apply is not a function" error while using Gitbook
       ... https://flaviocopes.com/cb-apply-not-a-function/
       > a real hack:
       * this guy commented out code in node_modules:
         node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js

           >>> PUNT and DO THIS (this is how I got it working):
         - in MY case the problem code is found here:
           c:/dev/tw-themes/node_modules/npm/node_modules/graceful-fs/polyfills.js
           * comment out the lines 62-64:
             // KJB: HACK to fix STALE gitbook-cli (see: TOOLING.md)
             // fs.stat = statFix(fs.stat)
             // fs.fstat = statFix(fs.fstat)
             // fs.lstat = statFix(fs.lstat)
           * IT WORKS!

- The docs server will crash when any docs files change.
  ... this was even happening when I developed my other project's docs.
  >>> JUST PUNT and live with this.

  8. Follow customization suggestions found in Integrating GitBook with JSDoc to Document Your Open Source Project.

    Specifically:

    • Setup docs/styles/website.css
    • Disable livereload via "-livereload" option in "plugins" section of book.json
    • Disable social media sharing in toolbar via "-sharing" option in "plugins" section of book.json
    • Adding toolbar links to GitHub/NPM via "toolbar" plugin (configured in book.json). Don't forget to do your $ npx gitbook install to install the toolbar plugin referenced in book.json.

  9. Install folding-menu GitBook plugin that "tames" large left-nav menus by visualizing one section at a time.

    • add following to book.json:

      book.json

      {
  ...
  "plugins": [
    ... other plugins you may be using
    "folding-menu"
  ]
  ...
  "pluginsConfig": {
    "folding-menu":	{
      "animationDuration": 500,
      "sticky":            false
    }
  }
}

      There appears to be a bug in the folding-menu plugin "sticky" setting, where it is NOT informed of a top-level page change when done via a link. As a result I have disabled this option ("sticky": false).

    • install the new plugins

      $ npx gitbook install

    info: installing 2 plugins using [email protected] 
    info: installing plugin "toolbar" 
    info: install plugin "toolbar" (*) from NPM with version 0.6.0 
    info: >> plugin "toolbar" installed with success 
    info:  
    info: installing plugin "folding-menu" 
    info: install plugin "folding-menu" (*) from NPM with version 1.0.1 
    info: >> plugin "folding-menu" installed with success 

> NOT (OLD):
$ npm install --save-dev gitbook-plugin-folding-menu

Setup js.org sub-domain

To accommodate a more professional URL, js.org supports a sub-domain registration process.

At the end of this process you should have:

To accomplish this, simply follow the instructions on js.org. Here is my summary (more notes hidden here in comment form):

 - First setup a preliminary set of docs that are deployable to
   [GitHub Pages].  `js.org` requires "reasonable content" before
   they will approve your request.  Alternatively you can create
   some temporary content that shows your intent.


 - Create a CNAME file at gh-pages root.  In our case this will live
   in `docs/`:
   
   * docs/CNAME
     ==========
     tw-themes.js.org

   * Deploy your latest docs to [GitHub Pages]:

     ```
     $ npm run docs:publish
     ```

     NOTE: Once this is done, you will not be able to browse your gh-pages
           till js.org processes your PR (below).

 - Fork the `js.org` project and issue a PR to introduce our sub-domain
   * new entry in: cnames_active.js
     ... "tw-themes": "kevinast.github.io/tw-themes",

 - Monitor PR acceptance (will take 24 hrs).

 - Once complete the sub-domain should be active

   NOTE: the original gh-pages link to the new sub-domain

Setup Lib Packaging

This task will setup the tooling needed to package and deploy the tw-themes library to NPM.

Currently we use a very simple packaging process that employs babel only. In other words, no bundler is used (such as webpack or rollup).

Links: How to publish a npm package?

At the end of this process you should have:

  • The ability to deploy the tw-themes library to NPM.

  • Impacted Dependencies:

    @babel/cli
@babel/core
@babel/preset-env

  • Impacted Files:

    tw-themes/
  .gitignore
  package.json
  babel.config.js

Installation Details:

  • Install required dependencies (Babel).

    NOTE: Some of these dependencies overlap with other setup (Install only what is missing):

    $ npm install --save-dev @babel/core @babel/preset-env @babel/cli

  • modify package.json with deployment-specific fields:

    package.json (leave comments out):

    {
  "name": "tw-themes",    // the name of the npm package
  "version": "0.1.0",     // the npm package version

                          // referenced in npm registry
  "description": "powerful tailwind color themes (dynamically selectable at run-time)",
  "homepage": "https://tw-themes.js.org/",
  "repository": {
    "type": "git",
    "url": "https://github.com/KevinAst/tw-themes.git"
  },
  "bugs": {
    "url": "https://github.com/KevinAst/tw-themes/issues"
  },
  "keywords": [
    "tailwind",
    "themes",
    "theme",
    "dark",
    "dark-mode",
    "colors",
    "web",
    "utility",
    "geeku",
    "astx"
  ],
  "author": "Kevin J. Bridges <[email protected]> (https://github.com/KevinAst)",
  "license": "MIT",

  "main": "lib/index.js", // references the generated library bundle

  "files": [              // resources to include in the NPM package
    "package.json",
    "LICENSE.md",
    "README.md",
    "lib",
    "src"
  ],

  ... snip snip
}

  • Configure Babel:

    babel.config.js:

    module.exports = {
  presets: [
    "@babel/preset-env"
  ]
}

  • define a src/.npmignore to omit modules that should NOT be included in the bundle (ex: unit tests):

    src/.npmignore

    # do NOT publish any spec/ directory (unit tests spread throughout our src/ code base)
spec

  • Setup the lib: NPM Scripts:

    package.json (leave comments out):

    {
  ...

  "scripts": {
    ...

    "lib:build":    "babel src --out-dir lib --no-comments",

    "prelib:build": "npm run test", // don't build unless unit tests are OK

    "lib:clean":    "rimraf lib"

    "prepare":      "npm run lib:build", // run build before `$ npm publish`
  },

  ... snip snip
}

  • Adjust .gitignore:

    .gitignore

    # bundled NPM distribution (generated via "npm run lib:build")
# ... currently only using /lib/
/dist/
/lib/
/es/

  • Verify a manual build:

    $ run npm lib:build # see results in `lib/` directory

Deploy Project

This section chronicles the steps in deploying tw-themes to NPM.

Feature Branch:

Typically all development is done in a feature branch. If you are about to deploy, presumably your branch is complete and documented.

  1. insure all tests are operational

    $ npm run test

  2. finalize version -and- history notes:

    • for the new version, use semantic standards

    • update version in:

      • package.json
      • docs/toc.md (version is referenced at top)
      • docs/history.md (within the "running" notes)

    • review/finalize all documentation impacted by change

      • also insure README.md does NOT need to change

    • optionally: save a link-neutral version of change history comments (to use in git tagging)

main Branch:

  1. issue PR (pull request) and merge to main branch

  2. sync main to local machine (where the deployment will occur)

  3. verify version is correct in:

    • package.json
    • docs/toc.md
    • docs/history.md

  4. now, everything should be checked in to main and ready to publish

  5. tag the release (in github)

    • verify the history page github links are correct (now that the tag exists)

  6. publish tw-themes to npm (THIS IS IT!):

     $ npm publish
   + [email protected]

    verify publish was successful

  7. publish tw-themes documentation:

    $ npm run docs:publish

    verify publish docs was successful

  8. optionally test the new package in an external project (by installing it)

Setup New Feature Branch

This section documents the steps to setup a new feature branch (where all development is typically done):

  1. create a new branch (typically spawned from the "main" branch).

    EX: next7

  2. devise "best guess" as to the next version number (may be premature, but this can subsequently change).

    Reflect this in:

    • package.json
    • docs/toc.md (version is referenced at top)
    • docs/history.md (within the "running" notes)

  3. setup new running Revision History (in docs/history.md)

    This provides a place where we can incrementally maintain "running" revision notes.