|
| 1 | +# Publishing Guide |
| 2 | + |
| 3 | +This guide explains how to publish the `tauri-plugin-sqlite` to both |
| 4 | +crates.io (Rust) and npm (JavaScript/TypeScript). |
| 5 | + |
| 6 | +## Overview |
| 7 | + |
| 8 | +This Tauri plugin has two primary artifacts that need to be published: |
| 9 | + |
| 10 | +1. **Rust crate** (`tauri-plugin-sqlite`) - Published to |
| 11 | + [crates.io](https://crates.io) |
| 12 | +2. **NPM package** (`@silvermine/tauri-plugin-sqlite`) - Published to |
| 13 | + [npmjs.com](https://www.npmjs.com) |
| 14 | + |
| 15 | +## Prerequisites |
| 16 | + |
| 17 | +### For Rust (crates.io) |
| 18 | + |
| 19 | + * A [crates.io](https://crates.io) account |
| 20 | + * Authentication token configured: `cargo login <your-token>` |
| 21 | + * Write permissions to the `tauri-plugin-sqlite` crate (for updates) |
| 22 | + |
| 23 | +### For NPM |
| 24 | + |
| 25 | + * An [npm](https://www.npmjs.com) account |
| 26 | + * Authentication configured: `npm login` or `npm adduser` |
| 27 | + * Member of the `@silvermine` organization (or owner) |
| 28 | + * Write permissions to the `@silvermine/tauri-plugin-sqlite` package |
| 29 | + (for updates) |
| 30 | + |
| 31 | +## Pre-Publishing Checklist |
| 32 | + |
| 33 | +Before publishing, ensure: |
| 34 | + |
| 35 | + * [ ] All tests pass: `cargo test` |
| 36 | + * [ ] Code passes linting: `npm run standards` |
| 37 | + * [ ] JavaScript is built: `npm run build` |
| 38 | + * [ ] Version numbers are updated in both `Cargo.toml` and `package.json` |
| 39 | + * [ ] CHANGELOG is updated with release notes |
| 40 | + * [ ] README is up to date |
| 41 | + * [ ] All changes are committed to git |
| 42 | + |
| 43 | +## Publishing Steps |
| 44 | + |
| 45 | +### 1. Update Version Numbers |
| 46 | + |
| 47 | +Update the version in both files to match (e.g., `0.2.0`): |
| 48 | + |
| 49 | +#### Cargo.toml |
| 50 | + |
| 51 | +```toml |
| 52 | +[package] |
| 53 | +version = "0.2.0" |
| 54 | +``` |
| 55 | + |
| 56 | +#### package.json |
| 57 | + |
| 58 | +```json |
| 59 | +{ |
| 60 | + "version": "0.2.0" |
| 61 | +} |
| 62 | +``` |
| 63 | + |
| 64 | +### 2. Build JavaScript Artifacts |
| 65 | + |
| 66 | +```bash |
| 67 | +npm run build |
| 68 | +``` |
| 69 | + |
| 70 | +This creates the distribution files in `dist-js/`: |
| 71 | + |
| 72 | + * `index.js` (ESM) |
| 73 | + * `index.cjs` (CommonJS) |
| 74 | + * `index.d.ts` (TypeScript declarations) |
| 75 | + |
| 76 | +And the IIFE bundle: |
| 77 | + |
| 78 | + * `api-iife.js` |
| 79 | + |
| 80 | +### 3. Verify Package Contents |
| 81 | + |
| 82 | +#### Rust Package |
| 83 | + |
| 84 | +```bash |
| 85 | +cargo package --list --allow-dirty |
| 86 | +``` |
| 87 | + |
| 88 | +This should include: |
| 89 | + |
| 90 | + * `src/` - Rust source code |
| 91 | + * `permissions/` - Tauri permission definitions |
| 92 | + * `build.rs` - Build script |
| 93 | + * `Cargo.toml` - Package manifest |
| 94 | + * `LICENSE` - MIT license |
| 95 | + * `README.md` - Documentation |
| 96 | + |
| 97 | +#### NPM Package |
| 98 | + |
| 99 | +```bash |
| 100 | +npm pack --dry-run |
| 101 | +``` |
| 102 | + |
| 103 | +This should include: |
| 104 | + |
| 105 | + * `dist-js/` - Built JavaScript files |
| 106 | + * `permissions/` - Tauri permission definitions |
| 107 | + * `LICENSE` - MIT license |
| 108 | + * `README.md` - Documentation |
| 109 | + * `package.json` - Package manifest |
| 110 | + |
| 111 | +### 4. Test the Packages Locally |
| 112 | + |
| 113 | +#### Test Rust Package |
| 114 | + |
| 115 | +```bash |
| 116 | +# Create a test package (doesn't publish) |
| 117 | +cargo package --allow-dirty |
| 118 | + |
| 119 | +# The package will be in target/package/tauri-plugin-sqlite-X.Y.Z.crate |
| 120 | +# You can test it in another project with: |
| 121 | +# cargo add --path /path/to/target/package/tauri-plugin-sqlite-X.Y.Z |
| 122 | +``` |
| 123 | + |
| 124 | +#### Test NPM Package |
| 125 | + |
| 126 | +```bash |
| 127 | +# Create a tarball |
| 128 | +npm pack |
| 129 | + |
| 130 | +# This creates: silvermine-tauri-plugin-sqlite-X.Y.Z.tgz |
| 131 | +# You can test it in another project with: |
| 132 | +# npm install /path/to/silvermine-tauri-plugin-sqlite-X.Y.Z.tgz |
| 133 | +``` |
| 134 | + |
| 135 | +### 5. Publish to crates.io |
| 136 | + |
| 137 | +```bash |
| 138 | +# Publish the Rust crate |
| 139 | +cargo publish |
| 140 | +``` |
| 141 | + |
| 142 | +If you need to do a dry run first: |
| 143 | + |
| 144 | +```bash |
| 145 | +cargo publish --dry-run |
| 146 | +``` |
| 147 | + |
| 148 | +### 6. Publish to npm |
| 149 | + |
| 150 | +```bash |
| 151 | +# Publish the NPM package |
| 152 | +npm publish --access public |
| 153 | +``` |
| 154 | + |
| 155 | +**Note**: The `--access public` flag is required for scoped packages (@silvermine). |
| 156 | + |
| 157 | +If you need to do a dry run first: |
| 158 | + |
| 159 | +```bash |
| 160 | +npm publish --dry-run |
| 161 | +``` |
| 162 | + |
| 163 | +### 7. Create a Git Tag |
| 164 | + |
| 165 | +```bash |
| 166 | +git tag -a v0.2.0 -m "Release version 0.2.0" |
| 167 | +git push origin v0.2.0 |
| 168 | +``` |
| 169 | + |
| 170 | +### 8. Create a GitHub Release |
| 171 | + |
| 172 | +1. Go to the [Releases page](https://github.com/silvermine/tauri-plugin-sqlite/releases) |
| 173 | +2. Click "Draft a new release" |
| 174 | +3. Select the tag you just created |
| 175 | +4. Add release notes (copy from CHANGELOG) |
| 176 | +5. Publish the release |
| 177 | + |
| 178 | +## Post-Publishing Verification |
| 179 | + |
| 180 | +After publishing, verify the packages are available: |
| 181 | + |
| 182 | +### Crates.io |
| 183 | + |
| 184 | +Visit: <https://crates.io/crates/tauri-plugin-sqlite> |
| 185 | + |
| 186 | +Or test installation in a new project: |
| 187 | + |
| 188 | +```bash |
| 189 | +cargo add tauri-plugin-sqlite |
| 190 | +``` |
| 191 | + |
| 192 | +### NPM |
| 193 | + |
| 194 | +Visit: <https://www.npmjs.com/package/@silvermine/tauri-plugin-sqlite> |
| 195 | + |
| 196 | +Or test installation in a new project: |
| 197 | + |
| 198 | +```bash |
| 199 | +npm install @silvermine/tauri-plugin-sqlite |
| 200 | +``` |
| 201 | + |
| 202 | +## Troubleshooting |
| 203 | + |
| 204 | +### "crate already exists" Error |
| 205 | + |
| 206 | +If you see this error from `cargo publish`, the version you're trying to |
| 207 | +publish already exists. You cannot overwrite a published version on crates.io. |
| 208 | +You need to increment the version number. |
| 209 | + |
| 210 | +### "cannot publish package with no version" Error |
| 211 | + |
| 212 | +Make sure the version is set in both `Cargo.toml` and `package.json`. |
| 213 | + |
| 214 | +### "You do not have permission to publish" Error |
| 215 | + |
| 216 | +For crates.io: |
| 217 | + |
| 218 | + * You need to be added as an owner: |
| 219 | + `cargo owner --add <username> tauri-plugin-sqlite` |
| 220 | + |
| 221 | +For npm: |
| 222 | + |
| 223 | + * You need to be a member of the `@silvermine` organization |
| 224 | + * Contact the organization admin |
| 225 | + |
| 226 | +### Package Size Too Large |
| 227 | + |
| 228 | +If you get warnings about package size: |
| 229 | + |
| 230 | +For Rust: Check the `include` field in `Cargo.toml` to ensure you're not |
| 231 | +including unnecessary files. |
| 232 | + |
| 233 | +For npm: Check the `files` field in `package.json`. |
| 234 | + |
| 235 | +## Version Compatibility |
| 236 | + |
| 237 | +When publishing, consider version compatibility: |
| 238 | + |
| 239 | + * **Rust crate**: Follow [Semantic Versioning](https://semver.org/) |
| 240 | + * **NPM package**: Also follows Semantic Versioning |
| 241 | + * Keep both versions in sync (same version number) |
| 242 | + |
| 243 | +## Dependencies |
| 244 | + |
| 245 | +Both packages have dependencies that should be kept up to date: |
| 246 | + |
| 247 | +### Rust Dependencies |
| 248 | + |
| 249 | + * `tauri` - Should match the Tauri version your plugin supports |
| 250 | + * `sqlx` - Database library version |
| 251 | + |
| 252 | +### NPM Dependencies |
| 253 | + |
| 254 | + * `@tauri-apps/api` - Must be a peer dependency (not bundled) |
| 255 | + |
| 256 | +## Additional Resources |
| 257 | + |
| 258 | + * [Cargo Publishing Guide](https://doc.rust-lang.org/cargo/reference/publishing.html) |
| 259 | + * [NPM Publishing Guide](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry) <!-- markdownlint-disable-line MD013 --> |
| 260 | + * [Tauri Plugin Documentation](https://tauri.app/develop/plugins/) |
0 commit comments