Firefly Semantics Lit Element Starter Project

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

It makes collaborating with, building, testing, documenting, and releasing / publishing Typescript 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
• Typedoc 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 git@github.com:fireflysemantics/fs-typescript-starter.git

Setup

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

cd fs-typescript-starter
npm i

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

Typedoc the Project

npm run doc

To clean the doc directory run:

npm run clean:doc

To serve the typedoc locally run:

npm run sdoc

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.

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 demo

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.