From af8fff8da9b4c9c9dfa0a862ff383f24136491aa Mon Sep 17 00:00:00 2001 From: Chris Zuber Date: Sun, 4 Feb 2024 23:48:56 -0800 Subject: [PATCH] Initial setup --- .npmignore | 1 + CHANGELOG.md | 61 +- README.md | 137 ++- cjs/.gitkeep | 0 index.js | 9 +- package-lock.json | 2267 +++++++++++++++++++++++++++++++++++---------- package.json | 53 +- rollup.config.js | 17 +- test/dad-joke.js | 71 ++ test/icons.js | 5 + test/index.html | 35 + 11 files changed, 2077 insertions(+), 579 deletions(-) delete mode 100644 cjs/.gitkeep create mode 100644 test/dad-joke.js create mode 100644 test/icons.js create mode 100644 test/index.html diff --git a/.npmignore b/.npmignore index fbf5394..78b7a35 100644 --- a/.npmignore +++ b/.npmignore @@ -1,5 +1,6 @@ node_modules/ .github/ +test/ .editorconfig .eslintignore .eslintrc.json diff --git a/CHANGELOG.md b/CHANGELOG.md index 74c324a..1feeb68 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,65 +6,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] -### Changed -- Setup to transpile all `./*.js` to `./cjs/*.cjs` (except `*.config.js`) -- Update `exports` and `main` accordingly - -## [v1.1.1] - 2023-09-24 - -### Added -- Add `unpkg` to `package.json` -- Add badges in README - -### Changed -- Update `exports` to `package.json` to handle wider variety - -### Fixed -- Fix typo in `fix:js` script - -### [v1.1.0] - 2023-07-03 - -### Changed -- Update to node 20 -- Update npm publishing GH Action - -## [v1.0.5] - 2023-07-02 - -### Added -- Add `funding` - -### Changed -- Updated GitHub Actions workflows -- Update versioning & lock-file scripts -- Update `.npmignore` & `.gitignore` - -## [v1.0.4] - 2023-06-08 - -### Added -- Install `@shgysk8zer0/npm-utils` -- Add `exports` to package config - -### Removed -- Uninstall `rollup`, `eslint` - -### Changed -- Use `getConfig()` from `@shgysk8zer0/js-utils/rollup` for rollup config - -## [v1.0.3] - 2023-06-01 - -### Fixed -- Revert to old Release Action, now with permissions & link to changelog - -## [v1.0.2] - 2023-06-01 - -### Fixed -- Fix `changelog-entry` to match `[$version]` instead of `$version` - -## [v1.0.1] - 2023-05-31 - -### Fixed -- Update GitHub Release workflow to use [Auto Release](https://github.com/marketplace/actions/auto-release) - -## [v1.0.0] - 2023-05-31 +## [v0.0.1] - 2024-02-04 Initial Release diff --git a/README.md b/README.md index b53d4f8..61f1f49 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,14 @@ -# npm-template +# `@shgysk8zer0/aegis-component-template` -A template repo for npm packages +Template repository for [`@shgysk8zer0/aegis-component`](https://github.com/shgysk8zer0/aegis-component) components -[![CodeQL](https://github.com/shgysk8zer0/node-http/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/shgysk8zer0/npm-template/actions/workflows/codeql-analysis.yml) -![Node CI](https://github.com/shgysk8zer0/node-http/workflows/Node%20CI/badge.svg) -![Lint Code Base](https://github.com/shgysk8zer0/node-http/workflows/Lint%20Code%20Base/badge.svg) +[![CodeQL](https://github.com/shgysk8zer0/aegis-component-template/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/shgysk8zer0/npm-template/actions/workflows/codeql-analysis.yml) +![Node CI](https://github.com/shgysk8zer0/aegis-component-template/workflows/Node%20CI/badge.svg) +![Lint Code Base](https://github.com/shgysk8zer0/aegis-component-template/workflows/Lint%20Code%20Base/badge.svg) -[![GitHub license](https://img.shields.io/github/license/shgysk8zer0/node-http.svg)](https://github.com/shgysk8zer0/node-http/blob/master/LICENSE) -[![GitHub last commit](https://img.shields.io/github/last-commit/shgysk8zer0/node-http.svg)](https://github.com/shgysk8zer0/node-http/commits/master) -[![GitHub release](https://img.shields.io/github/release/shgysk8zer0/node-http?logo=github)](https://github.com/shgysk8zer0/node-http/releases) +[![GitHub license](https://img.shields.io/github/license/shgysk8zer0/aegis-component-template.svg)](https://github.com/shgysk8zer0/aegis-component-template/blob/master/LICENSE) +[![GitHub last commit](https://img.shields.io/github/last-commit/shgysk8zer0/aegis-component-template.svg)](https://github.com/shgysk8zer0/aegis-component-template/commits/master) +[![GitHub release](https://img.shields.io/github/release/shgysk8zer0/aegis-component-template?logo=github)](https://github.com/shgysk8zer0/aegis-component-template/releases) [![GitHub Sponsors](https://img.shields.io/github/sponsors/shgysk8zer0?logo=github)](https://github.com/sponsors/shgysk8zer0) [![npm](https://img.shields.io/npm/v/@shgysk8zer0/npm-template)](https://www.npmjs.com/package/@shgysk8zer0/npm-template) @@ -17,8 +17,8 @@ A template repo for npm packages [![npm](https://img.shields.io/npm/dw/@shgysk8zer0/npm-template?logo=npm)](https://www.npmjs.com/package/@shgysk8zer0/npm-template) [![GitHub followers](https://img.shields.io/github/followers/shgysk8zer0.svg?style=social)](https://github.com/shgysk8zer0) -![GitHub forks](https://img.shields.io/github/forks/shgysk8zer0/node-http.svg?style=social) -![GitHub stars](https://img.shields.io/github/stars/shgysk8zer0/node-http.svg?style=social) +![GitHub forks](https://img.shields.io/github/forks/shgysk8zer0/aegis-component-template.svg?style=social) +![GitHub stars](https://img.shields.io/github/stars/shgysk8zer0/aegis-component-template.svg?style=social) [![Twitter Follow](https://img.shields.io/twitter/follow/shgysk8zer0.svg?style=social)](https://twitter.com/shgysk8zer0) [![Donate using Liberapay](https://img.shields.io/liberapay/receives/shgysk8zer0.svg?logo=liberapay)](https://liberapay.com/shgysk8zer0/donate "Donate using Liberapay") @@ -27,3 +27,120 @@ A template repo for npm packages - [Code of Conduct](./.github/CODE_OF_CONDUCT.md) - [Contributing](./.github/CONTRIBUTING.md) + +This is a [GitHub Template Repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository) +to create components using [`@shgysk8zer0/aegis-component`](https://npmjs.com/package/aegis-component). +It serves as a quick-start to creating light-weight, secure, web standards based +components. It provides the essentials, such as: + +- The essential packages: + - [`@shgysk8zer0/aegis`](https://github.com/shgysk8zer0/aegis) + - [`@shgysk8zer0/aegis-styles`](https://github.com/shgysk8zer0/aegis-styles) + - [`@shgysk8zer0/aegis-component`](https://github.com/shgysk8zer0/aegis-component) +- Build tools + - [eslint](https://npmjs.com/eslint) + - [rollup](https://npmjs.com/rollup) +- [Dependabot](https://github.com/dependabot) & [CodeQL](https://github.com/github/codeql) config +- Pull Request & Issue templates +- Automated releases to npm on `git tag` (when pushed using `git push --tags`) +- Provides GitHub Action for Package Provenance + +To start creating your own component, just go to the [GitHub repo](https://github.com/shgysk8zer0/aegis-component-template) +and click the "Use this template" button. + +## Steps to Create a Component + +- Create Repository from the GitHub Template Repository +- Clone your new Aegis Component Repository +- Update the `README.md`, `package.json`, & `CHANGELOG.md` as needed (especially the name) +- Create your component +- Update `rollup.config.js` (don't forget to update `input` & `output.file`) +- Publish (create and merge PR) + +## Using Automated Releases + +The following setup will create an automated GitHub Release and publish on npm +for every signed git tag (`git tag -s vx.y.z`) pushed to GitHub: + +- Create a "Classic Token" (Automation) on [npmjs.org](https://www.npmjs.com/) +- Give that token a descriptive name name and copy it +- Paste it into your repository's "Repository secrets" in "settings" -> "Secrets and variables" -> Actions +- Done! + +Now, every time you create a new PGP signed tag on GitHub (don't forget to `git push --tags`) +it will create a new GitHub Release and a new release on npm with Package Provenance. + +## Example Component: + +```js +import { AegisComponent, registerComponent } from '@shgysk8zer0/aegis-component'; +import { html, appendTo } from '@shgysk8zer0/aegis'; + +registerComponent('hello-world', class HTMLHelloWorldElement extends AegisComponent { + constructor() { + super(({ shadow }) => appendTo(shadow, html`

Hello, World!

`)); + } +}); +``` + +## Package, Component, & Repository Requirements + +All packages **MUST** adhere to strict but fairly easy security guidelines: + +- All commits and tags **MUST** be [PGP/GPG signed](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits) +- All web-based commits **MUST** be signed off by the contributor (a setting in GitHub repo settings) +- All releases **MUST** use [Package Provenance](https://github.blog/2023-04-19-introducing-npm-package-provenance/) +- Components **MUST** adhere to a strict [Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) +- Components **MUST** comply with the provided [`TrustedTypesPolicy`](https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicy) or add their own, which **SHOULD**: + - Use `:component-name#html` for writing HTML as a string + - Use `:component-name#script-url` +- Components **MUST** be `import`able from a CDN (such as `unpkg.com`) without any build step/bundler +- Component **SHOULD** provide a ` + + + + + + + +