Skip to content

Commit 22d3e7a

Browse files
author
Test User
committed
feat: add npm publishing support
1 parent 02e0b74 commit 22d3e7a

File tree

7 files changed

+486
-1
lines changed

7 files changed

+486
-1
lines changed

‎.npmrc‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# npm configuration for DoPlan CLI
2+
3+
# Use public registry
4+
registry=https://registry.npmjs.org/
5+
6+
# Publish configuration
7+
# Note: Set NPM_TOKEN in CI/CD for automated publishing
8+
# For manual publishing, run: npm login
9+
10+
# Optional: Enable 2FA for publishing (recommended)
11+
# npm config set npm-two-factor-auth publish-only
12+
13+
# Optional: Set scope if publishing under organization
14+
# @scope:registry=https://registry.npmjs.org/
15+

‎NPM_SETUP.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# npm Publishing Setup - Complete ✅
2+
3+
This document confirms that npm publishing has been fully configured for the DoPlan CLI.
4+
5+
## What Was Configured
6+
7+
### 1. Package Configuration
8+
- ✅ `package.json` - Complete npm package configuration
9+
- Package name: `doplan-cli`
10+
- Version: `1.0.0` (synced with Go release)
11+
- Bin entry: `doplan` → `bin/doplan.js`
12+
- Keywords, author, license, repository configured
13+
- Publish config set to public registry
14+
15+
### 2. Wrapper Scripts
16+
- ✅ `bin/doplan.js` - Main wrapper script
17+
- Detects platform and architecture
18+
- Downloads binary from GitHub releases
19+
- Executes binary with all arguments
20+
- Handles errors gracefully
21+
22+
- ✅ `scripts/postinstall.js` - Post-install script
23+
- Automatically downloads binary after `npm install`
24+
- Runs during package installation
25+
26+
- ✅ `scripts/prepublish.js` - Pre-publish validation
27+
- Validates package.json structure
28+
- Checks required files exist
29+
- Validates version format
30+
31+
### 3. Configuration Files
32+
- ✅ `.npmrc` - npm configuration
33+
- Registry set to public npm registry
34+
- Ready for token-based authentication
35+
36+
- ✅ `.gitignore` - Updated to exclude npm files
37+
- `node_modules/`
38+
- `package-lock.json`
39+
- Binary cache directories
40+
41+
### 4. CI/CD Integration
42+
- ✅ `.github/workflows/release.yml` - Updated
43+
- New `publish-npm` job added
44+
- Automatically publishes to npm on tag push
45+
- Extracts version from git tag
46+
- Uses `NPM_TOKEN` secret for authentication
47+
48+
### 5. Documentation
49+
- ✅ `README.md` - Updated with npm installation instructions
50+
- ✅ `docs/development/NPM_PUBLISHING.md` - Complete publishing guide
51+
52+
## Next Steps
53+
54+
### To Enable Automated Publishing:
55+
56+
1. **Create npm Access Token:**
57+
```bash
58+
# Go to: https://www.npmjs.com/settings/YOUR_USERNAME/tokens
59+
# Create "Automation" token
60+
# Copy the token
61+
```
62+
63+
2. **Add to GitHub Secrets:**
64+
- Repository Settings → Secrets and variables → Actions
65+
- New repository secret
66+
- Name: `NPM_TOKEN`
67+
- Value: Your npm token
68+
- Save
69+
70+
3. **Test Publishing (Optional):**
71+
```bash
72+
# Login to npm
73+
npm login
74+
75+
# Test validation
76+
npm run prepublishOnly
77+
78+
# Publish manually (if needed)
79+
npm publish
80+
```
81+
82+
### To Publish a New Version:
83+
84+
1. **Create and push a git tag:**
85+
```bash
86+
git tag -a v1.0.1 -m "Release v1.0.1"
87+
git push origin v1.0.1
88+
```
89+
90+
2. **GitHub Actions will automatically:**
91+
- Build binaries with GoReleaser
92+
- Create GitHub release
93+
- Publish to npm with matching version
94+
95+
## Installation for Users
96+
97+
Users can now install via npm:
98+
99+
```bash
100+
# Global installation
101+
npm install -g doplan-cli
102+
103+
# Verify
104+
doplan --version
105+
```
106+
107+
## Package Details
108+
109+
- **Package Name:** `doplan-cli`
110+
- **npm URL:** https://www.npmjs.com/package/doplan-cli
111+
- **Registry:** https://registry.npmjs.org/
112+
- **Access:** Public
113+
- **Current Version:** 1.0.0
114+
115+
## File Structure
116+
117+
```
118+
.
119+
├── package.json # npm package configuration
120+
├── .npmrc # npm configuration
121+
├── bin/
122+
│ └── doplan.js # Wrapper script
123+
├── scripts/
124+
│ ├── postinstall.js # Post-install script
125+
│ └── prepublish.js # Pre-publish validation
126+
└── docs/development/
127+
└── NPM_PUBLISHING.md # Publishing guide
128+
```
129+
130+
## Verification
131+
132+
All files have been validated:
133+
- ✅ JavaScript syntax valid
134+
- ✅ Pre-publish validation passes
135+
- ✅ Package.json structure correct
136+
- ✅ All required files present
137+
138+
## Support
139+
140+
For issues or questions:
141+
- See `docs/development/NPM_PUBLISHING.md` for detailed guide
142+
- Check GitHub Actions workflow logs
143+
- Verify npm token permissions
144+
145+
---
146+
147+
**Status:** ✅ Ready for publishing
148+
**Last Updated:** $(date)
149+

‎README.md‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,19 @@ Whether you're building a web application, API service, mobile app, or any softw
5757
- **Git** (for version control)
5858
- **GitHub CLI** (`gh`) - Optional, for GitHub automation features
5959

60-
### Homebrew (Recommended)
60+
### npm (Recommended for Node.js users)
61+
62+
```bash
63+
# Install globally
64+
npm install -g doplan-cli
65+
66+
# Verify installation
67+
doplan --version
68+
```
69+
70+
**Note:** The npm package automatically downloads the correct binary for your platform during installation.
71+
72+
### Homebrew (Recommended for macOS/Linux)
6173

6274
```bash
6375
# Install from Homebrew tap (coming soon)

‎docs/development/NPM_PUBLISHING.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# npm Publishing Guide
2+
3+
This document describes how to publish the DoPlan CLI to npm.
4+
5+
## Overview
6+
7+
The DoPlan CLI is published to npm as `doplan-cli`. The npm package includes a wrapper script that automatically downloads the platform-specific binary from GitHub releases.
8+
9+
## Package Structure
10+
11+
- `package.json` - npm package configuration
12+
- `bin/doplan.js` - Wrapper script that downloads and executes the binary
13+
- `scripts/postinstall.js` - Post-install script that downloads the binary
14+
- `scripts/prepublish.js` - Pre-publish validation script
15+
- `.npmrc` - npm configuration
16+
17+
## Publishing Process
18+
19+
### Automated Publishing (Recommended)
20+
21+
Publishing to npm is automated via GitHub Actions. When you push a tag matching `v*`:
22+
23+
1. The release workflow builds binaries for all platforms
24+
2. Creates a GitHub release
25+
3. Automatically publishes to npm with the same version
26+
27+
**Requirements:**
28+
- `NPM_TOKEN` secret must be configured in GitHub repository settings
29+
- Token must have publish permissions for the `doplan-cli` package
30+
31+
### Manual Publishing
32+
33+
If you need to publish manually:
34+
35+
```bash
36+
# 1. Ensure you're logged in to npm
37+
npm login
38+
39+
# 2. Update version in package.json (if needed)
40+
npm version patch|minor|major
41+
42+
# 3. Run pre-publish validation
43+
npm run prepublishOnly
44+
45+
# 4. Publish to npm
46+
npm publish
47+
48+
# 5. Verify publication
49+
npm view doplan-cli
50+
```
51+
52+
## Setting up NPM_TOKEN
53+
54+
1. **Create an npm access token:**
55+
- Go to https://www.npmjs.com/settings/YOUR_USERNAME/tokens
56+
- Click "Generate New Token"
57+
- Select "Automation" token type
58+
- Copy the token
59+
60+
2. **Add to GitHub Secrets:**
61+
- Go to your repository settings
62+
- Navigate to Secrets and variables > Actions
63+
- Click "New repository secret"
64+
- Name: `NPM_TOKEN`
65+
- Value: Your npm token
66+
- Click "Add secret"
67+
68+
## Package Details
69+
70+
- **Package Name:** `doplan-cli`
71+
- **Registry:** https://registry.npmjs.org/
72+
- **Access:** Public
73+
- **Scoped:** No (public package)
74+
75+
## How It Works
76+
77+
1. **Installation:** When users run `npm install -g doplan-cli`:
78+
- npm installs the package files
79+
- `postinstall.js` runs automatically
80+
- Downloads the platform-specific binary from GitHub releases
81+
- Stores binary in `bin/<platform>-<arch>/doplan`
82+
83+
2. **Execution:** When users run `doplan`:
84+
- `bin/doplan.js` wrapper script is executed
85+
- Script detects platform and architecture
86+
- If binary doesn't exist, downloads it from GitHub releases
87+
- Executes the binary with all arguments
88+
89+
## Version Management
90+
91+
- Version in `package.json` should match the Go release version
92+
- GitHub Actions automatically syncs version from git tag
93+
- Use semantic versioning (e.g., `1.0.0`, `1.0.1`, `1.1.0`)
94+
95+
## Troubleshooting
96+
97+
### Binary Download Fails
98+
99+
If the binary download fails during installation:
100+
- Check GitHub releases exist for the version
101+
- Verify network connectivity
102+
- Users can manually download from GitHub releases
103+
104+
### Publishing Fails
105+
106+
If automated publishing fails:
107+
- Check `NPM_TOKEN` secret is set correctly
108+
- Verify token has publish permissions
109+
- Check package name isn't already taken
110+
- Ensure version doesn't already exist on npm
111+
112+
### Version Mismatch
113+
114+
If package.json version doesn't match release:
115+
- GitHub Actions automatically updates it from git tag
116+
- For manual publishing, ensure versions match
117+
118+
## Testing Before Publishing
119+
120+
```bash
121+
# Test package locally
122+
npm pack
123+
tar -xzf doplan-cli-*.tgz
124+
cd package
125+
npm install
126+
127+
# Test the wrapper script
128+
./bin/doplan.js --version
129+
130+
# Test installation simulation
131+
npm run prepublishOnly
132+
```
133+
134+
## Updating Package
135+
136+
To update the npm package:
137+
138+
1. Make changes to package files
139+
2. Update version (automated in CI/CD)
140+
3. Push git tag (triggers automated publish)
141+
4. Or publish manually with `npm publish`
142+
143+
## Package Files Included
144+
145+
The following files are included in the npm package (defined in `package.json` `files` field):
146+
147+
- `bin/` - Wrapper scripts
148+
- `scripts/` - Install and publish scripts
149+
- `README.md` - Package documentation
150+
- `LICENSE` - License file
151+
152+
Excluded files:
153+
- Source code (Go files)
154+
- Build artifacts
155+
- Test files
156+
- Development documentation
157+
158+
## Support
159+
160+
For issues with npm publishing:
161+
- Check GitHub Actions workflow logs
162+
- Verify npm token permissions
163+
- Review npm package page: https://www.npmjs.com/package/doplan-cli
164+

0 commit comments

Comments
 (0)