Skip to content

Commit a295388

Browse files
JorchCortezJorchCortez
committed
Add CI/CD workflows and publishing guide
Introduced GitHub Actions workflows for CI (ci.yml) and automated npm publishing (publish.yml). Added CI_CD_GUIDE.md with setup and usage instructions for the new workflows. Updated README.md with badges, contribution, and publishing information.
1 parent ac380f3 commit a295388

File tree

4 files changed

+250
-0
lines changed

4 files changed

+250
-0
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
test:
11+
runs-on: ubuntu-latest
12+
13+
strategy:
14+
matrix:
15+
node-version: [18, 20, 22]
16+
17+
steps:
18+
- name: Checkout code
19+
uses: actions/checkout@v4
20+
21+
- name: Setup Node.js ${{ matrix.node-version }}
22+
uses: actions/setup-node@v4
23+
with:
24+
node-version: ${{ matrix.node-version }}
25+
26+
- name: Install dependencies
27+
run: npm ci
28+
29+
- name: Run linter
30+
run: npm run lint
31+
32+
- name: Type check
33+
run: npm run type-check
34+
35+
- name: Build package
36+
run: npm run build
37+
38+
- name: Check build outputs
39+
run: |
40+
ls -la dist/
41+
echo "✅ Build completed successfully"

‎.github/workflows/publish.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
name: Publish to npm
2+
3+
on:
4+
release:
5+
types: [published]
6+
7+
jobs:
8+
publish:
9+
runs-on: ubuntu-latest
10+
11+
permissions:
12+
contents: read
13+
id-token: write # Required for provenance
14+
15+
steps:
16+
- name: Checkout code
17+
uses: actions/checkout@v4
18+
19+
- name: Setup Node.js
20+
uses: actions/setup-node@v4
21+
with:
22+
node-version: '20'
23+
registry-url: 'https://registry.npmjs.org'
24+
25+
- name: Install dependencies
26+
run: npm ci
27+
28+
- name: Build package
29+
run: npm run build
30+
31+
- name: Publish to npm
32+
run: npm publish --provenance --access public
33+
env:
34+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

‎CI_CD_GUIDE.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# CI/CD Publishing Guide
2+
3+
## Overview
4+
5+
This repository uses GitHub Actions to automatically publish to npm when you create a new release. No manual `npm publish` needed!
6+
7+
## 🔧 Setup (One-time)
8+
9+
### 1. Create an npm Access Token
10+
11+
1. Go to https://www.npmjs.com/settings/YOUR_USERNAME/tokens
12+
2. Click **"Generate New Token"** → **"Classic Token"**
13+
3. Select **"Automation"** type (for CI/CD)
14+
4. Copy the token (starts with `npm_...`)
15+
16+
### 2. Add Token to GitHub Secrets
17+
18+
1. Go to your GitHub repository
19+
2. Navigate to **Settings** → **Secrets and variables** → **Actions**
20+
3. Click **"New repository secret"**
21+
4. Name: `NPM_TOKEN`
22+
5. Value: Paste your npm token
23+
6. Click **"Add secret"**
24+
25+
## 🚀 Publishing Workflow
26+
27+
### Automated Publishing (Recommended)
28+
29+
1. **Update version in package.json**
30+
```bash
31+
npm version patch # 1.0.0 → 1.0.1 (bug fixes)
32+
# or
33+
npm version minor # 1.0.0 → 1.1.0 (new features)
34+
# or
35+
npm version major # 1.0.0 → 2.0.0 (breaking changes)
36+
```
37+
This creates a git tag automatically.
38+
39+
2. **Push the tag to GitHub**
40+
```bash
41+
git push
42+
git push --tags
43+
```
44+
45+
3. **Create a GitHub Release**
46+
- Go to your repository on GitHub
47+
- Click **"Releases"** → **"Create a new release"**
48+
- Select the tag you just pushed (e.g., `v1.0.1`)
49+
- Add release title (e.g., `v1.0.1`)
50+
- Add release notes describing changes
51+
- Click **"Publish release"**
52+
53+
4. **GitHub Actions takes over!**
54+
- Workflow runs automatically
55+
- Installs dependencies
56+
- Runs build
57+
- Publishes to npm
58+
- Check progress in **Actions** tab
59+
60+
### Manual Publishing (Fallback)
61+
62+
If you prefer manual publishing or need to bypass CI/CD:
63+
64+
```bash
65+
# 1. Build
66+
npm run build
67+
68+
# 2. Publish
69+
npm publish
70+
```
71+
72+
## 📋 What Each Workflow Does
73+
74+
### `publish.yml` - Publish to npm
75+
- **Trigger**: When you publish a GitHub release
76+
- **Actions**:
77+
- Checks out code
78+
- Sets up Node.js 20
79+
- Installs dependencies (`npm ci`)
80+
- Builds the package (`npm run build`)
81+
- Publishes to npm with provenance
82+
83+
### `ci.yml` - Continuous Integration
84+
- **Trigger**: On push to `main` or pull requests
85+
- **Actions**:
86+
- Tests on Node.js 18, 20, and 22
87+
- Runs linter (`npm run lint`)
88+
- Runs type checking (`npm run type-check`)
89+
- Builds the package
90+
- Verifies build outputs exist
91+
92+
## 🎯 Quick Publish Example
93+
94+
```bash
95+
# Make your changes, commit them
96+
git add .
97+
git commit -m "feat: add new feature"
98+
99+
# Bump version (creates git tag)
100+
npm version minor # 1.0.0 → 1.1.0
101+
102+
# Push code and tags
103+
git push && git push --tags
104+
105+
# Go to GitHub and create release from tag
106+
# → GitHub Actions automatically publishes to npm!
107+
```
108+
109+
## 🔍 Monitoring Builds
110+
111+
- Go to **Actions** tab in your GitHub repository
112+
- Click on the running workflow to see logs
113+
- Green checkmark = successful publish ✅
114+
- Red X = failed, click to see error logs ❌
115+
116+
## ⚠️ Important Notes
117+
118+
1. **npm token security**: Never commit your NPM_TOKEN to the repository
119+
2. **Provenance**: The workflow includes `--provenance` flag for supply chain security
120+
3. **Version must be bumped**: npm won't allow publishing the same version twice
121+
4. **Tests run on every push**: CI workflow ensures code quality before you release
122+
123+
## 🛠️ Troubleshooting
124+
125+
### "Error: Unable to authenticate"
126+
- Check that NPM_TOKEN secret is set correctly in GitHub
127+
- Verify the token hasn't expired
128+
- Regenerate token if needed
129+
130+
### "Error: Version already exists"
131+
- Bump the version in package.json
132+
- Run `npm version patch/minor/major`
133+
134+
### "Build failed"
135+
- Check the workflow logs in Actions tab
136+
- Test locally with `npm run build`
137+
- Ensure all dependencies are in package.json
138+
139+
### "Cannot find package after publishing"
140+
- Wait a few minutes (npm registry can take time to update)
141+
- Check https://www.npmjs.com/package/use-async-view
142+
- Verify package was published successfully in Actions logs
143+
144+
## 🎉 Benefits of CI/CD
145+
146+
✅ **Consistent builds** - Same environment every time
147+
✅ **No manual steps** - Automated testing and publishing
148+
✅ **Provenance** - Cryptographically signed packages
149+
✅ **Multi-Node testing** - Ensures compatibility
150+
✅ **Release notes** - GitHub releases document changes
151+
✅ **Rollback friendly** - Tag-based versioning
152+
153+
## 📚 Additional Resources
154+
155+
- [npm provenance documentation](https://docs.npmjs.com/generating-provenance-statements)
156+
- [GitHub Actions documentation](https://docs.github.com/en/actions)
157+
- [Semantic Versioning (semver)](https://semver.org/)

‎README.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
# useAsyncView Hook
22

3+
[![npm version](https://badge.fury.io/js/use-async-view.svg)](https://www.npmjs.com/package/use-async-view)
4+
[![npm downloads](https://img.shields.io/npm/dm/use-async-view.svg)](https://www.npmjs.com/package/use-async-view)
5+
[![CI](https://github.com/JorchCortez/use-async-view/actions/workflows/ci.yml/badge.svg)](https://github.com/JorchCortez/use-async-view/actions/workflows/ci.yml)
6+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
7+
38
A custom React hook that manages asynchronous data loading with automatic view rendering based on the current loading state.
49

510
## Features
@@ -515,3 +520,16 @@ export default defineConfig([
515520
},
516521
])
517522
```
523+
## Contributing
524+
525+
Contributions are welcome! This project uses GitHub Actions for CI/CD.
526+
527+
### Publishing
528+
529+
This package uses automated publishing via GitHub Actions. See [CI_CD_GUIDE.md](./CI_CD_GUIDE.md) for details on the automated workflow.
530+
531+
For manual publishing instructions, see [PUBLISHING.md](./PUBLISHING.md).
532+
533+
## License
534+
535+
MIT © [JorchCortez](https://github.com/JorchCortez)

0 commit comments

Comments
 (0)