mirror of
https://github.com/LukeHagar/stats-action.git
synced 2025-12-06 04:21:26 +00:00
saving stats action progress
This commit is contained in:
Luke Hagar
232
README.md
232
README.md
@@ -1,205 +1,61 @@
|
||||
# Create a JavaScript Action
|
||||
# vite-vanilla-ts-lib-starter
|
||||
|
||||
[](https://github.com/super-linter/super-linter)
|
||||
|
||||
The starter is built on top of Vite 5.x and prepared for writing libraries in TypeScript. It generates a hybrid package - both support for CommonJS and ESM modules.
|
||||
|
||||
Use this template to bootstrap the creation of a JavaScript action. :rocket:
|
||||
## Features
|
||||
|
||||
This template includes compilation support, tests, a validation workflow,
|
||||
publishing, and versioning guidance.
|
||||
- Hybrid support - CommonJS and ESM modules
|
||||
- IIFE bundle for direct browser support without bundler
|
||||
- Typings bundle
|
||||
- ESLint - scripts linter
|
||||
- Stylelint - styles linter
|
||||
- Prettier - formatter
|
||||
- Vitest - test framework
|
||||
- Husky + lint-staged - pre-commit git hook set up for formatting
|
||||
|
||||
If you are new, there's also a simpler introduction in the
|
||||
[Hello world JavaScript action repository](https://github.com/actions/hello-world-javascript-action).
|
||||
## GitHub Template
|
||||
|
||||
## Create Your Own Action
|
||||
This is a template repo. Click the green [Use this template](https://github.com/kbysiec/vite-vanilla-ts-lib-starter/generate) button to get started.
|
||||
|
||||
To create your own action, you can use this repository as a template! Just
|
||||
follow the below instructions:
|
||||
## Clone to local
|
||||
|
||||
1. Click the **Use this template** button at the top of the repository
|
||||
1. Select **Create a new repository**
|
||||
1. Select an owner and name for your new repository
|
||||
1. Click **Create repository**
|
||||
1. Clone your new repository
|
||||
If you prefer to do it manually with the cleaner git history
|
||||
|
||||
> [!IMPORTANT]
|
||||
>
|
||||
> Make sure to remove or update the [`CODEOWNERS`](./CODEOWNERS) file! For
|
||||
> details on how to use this file, see
|
||||
> [About code owners](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners).
|
||||
|
||||
## Initial Setup
|
||||
|
||||
After you've cloned the repository to your local machine or codespace, you'll
|
||||
need to perform some initial setup steps before you can develop your action.
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> You'll need to have a reasonably modern version of
|
||||
> [Node.js](https://nodejs.org) handy. If you are using a version manager like
|
||||
> [`nodenv`](https://github.com/nodenv/nodenv) or
|
||||
> [`nvm`](https://github.com/nvm-sh/nvm), you can run `nodenv install` in the
|
||||
> root of your repository to install the version specified in
|
||||
> [`package.json`](./package.json). Otherwise, 20.x or later should work!
|
||||
|
||||
1. :hammer_and_wrench: Install the dependencies
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
1. :building_construction: Package the JavaScript for distribution
|
||||
|
||||
```bash
|
||||
npm run bundle
|
||||
```
|
||||
|
||||
1. :white_check_mark: Run the tests
|
||||
|
||||
```bash
|
||||
$ npm test
|
||||
|
||||
PASS ./index.test.js
|
||||
✓ throws invalid number (3ms)
|
||||
✓ wait 500 ms (504ms)
|
||||
✓ test runs (95ms)
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
## Update the Action Metadata
|
||||
|
||||
The [`action.yml`](action.yml) file defines metadata about your action, such as
|
||||
input(s) and output(s). For details about this file, see
|
||||
[Metadata syntax for GitHub Actions](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions).
|
||||
|
||||
When you copy this repository, update `action.yml` with the name, description,
|
||||
inputs, and outputs for your action.
|
||||
|
||||
## Update the Action Code
|
||||
|
||||
The [`src/`](./src/) directory is the heart of your action! This contains the
|
||||
source code that will be run when your action is invoked. You can replace the
|
||||
contents of this directory with your own code.
|
||||
|
||||
There are a few things to keep in mind when writing your action code:
|
||||
|
||||
- Most GitHub Actions toolkit and CI/CD operations are processed asynchronously.
|
||||
In `main.js`, you will see that the action is run in an `async` function.
|
||||
|
||||
```javascript
|
||||
const core = require('@actions/core')
|
||||
//...
|
||||
|
||||
async function run() {
|
||||
try {
|
||||
//...
|
||||
} catch (error) {
|
||||
core.setFailed(error.message)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For more information about the GitHub Actions toolkit, see the
|
||||
[documentation](https://github.com/actions/toolkit/blob/master/README.md).
|
||||
|
||||
So, what are you waiting for? Go ahead and start customizing your action!
|
||||
|
||||
1. Create a new branch
|
||||
|
||||
```bash
|
||||
git checkout -b releases/v1
|
||||
```
|
||||
|
||||
1. Replace the contents of `src/` with your action code
|
||||
1. Add tests to `__tests__/` for your source code
|
||||
1. Format, test, and build the action
|
||||
|
||||
```bash
|
||||
npm run all
|
||||
```
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> This step is important! It will run [`ncc`](https://github.com/vercel/ncc)
|
||||
> to build the final JavaScript action code with all dependencies included.
|
||||
> If you do not run this step, your action will not work correctly when it is
|
||||
> used in a workflow. This step also includes the `--license` option for
|
||||
> `ncc`, which will create a license file for all of the production node
|
||||
> modules used in your project.
|
||||
|
||||
1. Commit your changes
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "My first action is ready!"
|
||||
```
|
||||
|
||||
1. Push them to your repository
|
||||
|
||||
```bash
|
||||
git push -u origin releases/v1
|
||||
```
|
||||
|
||||
1. Create a pull request and get feedback on your action
|
||||
1. Merge the pull request into the `main` branch
|
||||
|
||||
Your action is now published! :rocket:
|
||||
|
||||
For information about versioning your action, see
|
||||
[Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
|
||||
in the GitHub Actions toolkit.
|
||||
|
||||
## Validate the Action
|
||||
|
||||
You can now validate the action by referencing it in a workflow file. For
|
||||
example, [`ci.yml`](./.github/workflows/ci.yml) demonstrates how to reference an
|
||||
action in the same repository.
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
- name: Checkout
|
||||
id: checkout
|
||||
uses: actions/checkout@v3
|
||||
|
||||
- name: Test Local Action
|
||||
id: test-action
|
||||
uses: ./
|
||||
with:
|
||||
milliseconds: 1000
|
||||
|
||||
- name: Print Output
|
||||
id: output
|
||||
run: echo "${{ steps.test-action.outputs.time }}"
|
||||
```bash
|
||||
git clone https://github.com/kbysiec/vite-vanilla-ts-lib-starter.git
|
||||
cd vite-vanilla-ts-lib-starter
|
||||
npm i
|
||||
```
|
||||
|
||||
For example workflow runs, check out the
|
||||
[Actions tab](https://github.com/actions/javascript-action/actions)! :rocket:
|
||||
## Checklist
|
||||
|
||||
When you use this template, update the following:
|
||||
|
||||
- Remove `.git` directory and run `git init` to clean up the history
|
||||
- Change the name in `package.json` - it will be the name of the IIFE bundle global variable and bundle files name (`.cjs`, `.mjs`, `.iife.js`, `d.ts`)
|
||||
- Change the author name in `LICENSE`
|
||||
- Clean up the `README` and `CHANGELOG` files
|
||||
|
||||
And, enjoy :)
|
||||
|
||||
## Usage
|
||||
|
||||
After testing, you can create version tag(s) that developers can use to
|
||||
reference different stable versions of your action. For more information, see
|
||||
[Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
|
||||
in the GitHub Actions toolkit.
|
||||
The starter contains the following scripts:
|
||||
|
||||
To include the action in a workflow in another repository, you can use the
|
||||
`uses` syntax with the `@` symbol to reference a specific branch, tag, or commit
|
||||
hash.
|
||||
- `dev` - starts dev server
|
||||
- `build` - generates the following bundles: CommonJS (`.cjs`) ESM (`.mjs`) and IIFE (`.iife.js`). The name of bundle is automatically taken from `package.json` name property
|
||||
- `test` - starts vitest and runs all tests
|
||||
- `test:coverage` - starts vitest and run all tests with code coverage report
|
||||
- `lint:scripts` - lint `.ts` files with eslint
|
||||
- `lint:styles` - lint `.css` and `.scss` files with stylelint
|
||||
- `format:scripts` - format `.ts`, `.html` and `.json` files with prettier
|
||||
- `format:styles` - format `.cs` and `.scss` files with stylelint
|
||||
- `format` - format all with prettier and stylelint
|
||||
- `prepare` - script for setting up husky pre-commit hook
|
||||
- `uninstall-husky` - script for removing husky from repository
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
- name: Checkout
|
||||
id: checkout
|
||||
uses: actions/checkout@v4
|
||||
## Acknowledgment
|
||||
|
||||
- name: Run my Action
|
||||
id: run-action
|
||||
uses: actions/javascript-action@v1 # Commit with the `v1` tag
|
||||
with:
|
||||
milliseconds: 1000
|
||||
If you found it useful somehow, I would be grateful if you could leave a star in the project's GitHub repository.
|
||||
|
||||
- name: Print Output
|
||||
id: output
|
||||
run: echo "${{ steps.run-action.outputs.time }}"
|
||||
```
|
||||
Thank you.
|
||||
|
||||
Reference in New Issue
Block a user