85 lines
2.7 KiB
Markdown
85 lines
2.7 KiB
Markdown
|
# Publishing @soulcraft/brainy and @soulcraft/brainy-cli to npm
|
||
|
|
|
||
|
|
This document explains how to publish both the @soulcraft/brainy and @soulcraft/brainy-cli packages to npm.
|
||
|
|
|
||
|
|
## Prerequisites
|
||
|
|
|
||
|
|
Before publishing, ensure you have:
|
||
|
|
|
||
|
|
1. Node.js >= 24.0.0 installed
|
||
|
|
2. An npm account with access to the @soulcraft organization
|
||
|
|
3. Logged in to npm using `npm login`
|
||
|
|
|
||
|
|
## Publishing Process
|
||
|
|
|
||
|
|
The repository is set up to publish both packages together with synchronized versions. To publish the packages, follow these steps:
|
||
|
|
|
||
|
|
### 1. Ensure you're in the root directory of the project
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cd /path/to/brainy
|
||
|
|
```
|
||
|
|
|
||
|
|
### 2. Make sure you have the latest version of the code
|
||
|
|
|
||
|
|
```bash
|
||
|
|
git pull
|
||
|
|
```
|
||
|
|
|
||
|
|
### 3. Build and publish both packages
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npm run deploy:both
|
||
|
|
```
|
||
|
|
|
||
|
|
This command will:
|
||
|
|
- Ensure versions are in sync between both packages
|
||
|
|
- Build the main package
|
||
|
|
- Build the CLI
|
||
|
|
- Verify the CLI was built successfully
|
||
|
|
- Publish the main package to npm
|
||
|
|
- Publish the CLI package to npm
|
||
|
|
|
||
|
|
### 4. Verify the packages were published successfully
|
||
|
|
|
||
|
|
After publishing, you can verify that the packages were published successfully by checking the npm registry:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npm view @soulcraft/brainy
|
||
|
|
npm view @soulcraft/brainy-cli
|
||
|
|
```
|
||
|
|
|
||
|
|
## How It Works
|
||
|
|
|
||
|
|
The publishing process uses the `scripts/publish-cli.js` script, which:
|
||
|
|
|
||
|
|
1. Ensures versions are in sync by running `scripts/generate-version.js`
|
||
|
|
2. Builds the main package with `npm run build`
|
||
|
|
3. Builds the CLI with `npm run build:cli`
|
||
|
|
4. Verifies the CLI was built successfully
|
||
|
|
5. Publishes the main package with `npm publish` from the root directory
|
||
|
|
6. Publishes the CLI package with `npm publish` from the cli-package directory
|
||
|
|
|
||
|
|
The version synchronization ensures that:
|
||
|
|
- Both packages always have the same version number
|
||
|
|
- The CLI package's dependency on the main package is exact (not using the ^ prefix)
|
||
|
|
- The README.md file is updated with the current version
|
||
|
|
|
||
|
|
The CLI package is configured in `cli-package/package.json` with:
|
||
|
|
- The correct package name: `@soulcraft/brainy-cli`
|
||
|
|
- `"private": false` to allow publishing
|
||
|
|
- `"publishConfig": { "access": "public" }` to ensure the scoped package is public
|
||
|
|
- The necessary files in the `"files"` array
|
||
|
|
- The correct bin configuration to make the CLI available as `brainy`
|
||
|
|
|
||
|
|
## Troubleshooting
|
||
|
|
|
||
|
|
If you encounter any issues during the publishing process:
|
||
|
|
|
||
|
|
1. Make sure you're logged in to npm with an account that has access to the @soulcraft organization
|
||
|
|
2. Ensure that the `dist/cli.js` file exists and has been built correctly
|
||
|
|
3. If you get an error about the package already existing, you may need to update the version in both package.json files:
|
||
|
|
```bash
|
||
|
|
npm version patch # This will update both package.json files via the version script
|
||
|
|
```
|