Firefly Semantics Javascript Starter Project

This is a baseline Javascript starter project that extends the Firefly Semantics Github Flow Starter Project.

It makes collaborating with, building, testing, documenting, and releasing / publishing Javascript ES2021 project modules simple.

The Github Flow Starter Project that it is based on provides documents that are commonly used in Github Flow open source projects and includes:

• MIT Licence
• Contributor Covenant Code of Conduct
• Contribution Guidelines
• Guidelines for Seeking Help
• Guidelines for Extending This Project
• Release and Changelog Automation with Release It!
• Commit Linting with commitlint
• Husky for triggering commit linting and on commit test automation and linting for projects extending this one.

The Github Flow Starter Project is setup to make following the Conventional Commits Specification for adding human and machine readable meaning to commit messages easy.

Following the Conventional Commits Specification encourages proper use of the Semantic Versioning Specification and also enables automatic generation of the projects changelog (CHANGELOG.md).

In addition to the capabilities added by the Github Flow Starter Project, this projects adds:

• Typescript ES2021 Module Build
• Central index.ts Module API Entry Point
• Testing with @web/test-runner
• JSDoc Documentation
• Rollup Module Bundling
• Module Declaration Properties in package.json

Get Started

To get started first clone or download the current release of this project.

Clone the Github Repository

git clone [email protected]:fireflysemantics/fs-javascript-starter.git

Setup

Install dependencies by cding into the root of the project and running npm i && npm run init.

cd fs-javascript-starter
npm i && npm run init

The npm run init script will install jsdoc globally, making it easier to run the command.

Run the default tests. If you get a message like this:

Looks like Playwright Test or Playwright was just installed or updated ...

Then run the script npm run playwright-init. This will download the browsers needed by playwright.

Lint the Project

To run eslint on the project:

npm run lint:eslint

Or

npm run lint

Build the Project

npm run build

To clean the build directory run:

npm run clean:build

To clean the entire project (Both the build directory and the doc directory) run:

npm run clean

Test the Project

npm run test

JSDoc the Project

npm run doc

To clean the doc directory run:

npm run clean:doc

To serve the jsdoc locally run:

npm run serve:doc

Deploy the docs to Github Pages with:

git subtree push --prefix doc origin gh-pages

This a link to the gist for the git subtree command.

To see the generated typedoc for this project click on this link.

Create a Rollup Module

npm run rollup

For more see rollup.

If the project is published NPM the index.bundle.js can be load from the UNPKG CDN via the URL https://unpkg.com/[package name]. So for example the URL for this projects index.bundle.js module is https://unpkg.com/fs-javascript-starter.

Here is a Stackblitz demo of this bundle loaded..

Publish the Project

npm run npm:pub

The release-it configuration in package.json sets publish to NPM to false, but it's also possible to use release-it to perform the publishing.

Unpublish the Project

npm run npm:unpub

Demo the Project

This will serve the index.html file located in the demo directory using @web/dev-server. The server resolves node style "bare" import specifiers, so there are no additional build steps.

npm run serve

Here is a link to the documentation for @web/dev-server.

Release the Project

Run release-it to perform a release.

npm run release

Review Project Commits

git log

Delete 2 Commits

git reset --hard HEAD~2

For more on deleting and cleaning up commit history this SO Post.

Keeping the commit history "Clean" and "Flowing" is creates a better experience for reviewers intersted in learning more about the project by running git log.