ReviewOS

also looking at this

loghqorg/loghq

Deploy: uniform auth session model (main → production)

#7
Merged glennmichael123 wants to merge main into production
282 files +3028 -64856
docs/bootcamp/how-to/publish.mddeleted+0-569
Changes to docs/bootcamp/how-to/publish.md
@@ -1,569 +0,0 @@
1# Publish
2
3This guide covers publishing packages and libraries from your Stacks application, including npm publishing, versioning, and package configuration.
4
5## Getting Started
6
7Stacks provides tools for building and publishing reusable packages to npm or other registries.
8
9```bash
10# Build and publish your library
11buddy publish
12```
13
14## Package Configuration
15
16### Library Configuration
17
18```ts
19// config/library.ts
20import type { LibraryConfig } from '@stacksjs/types'
21
22export default {
23 name: 'my-awesome-library',
24 description: 'A useful library built with Stacks',
25 author: 'Your Name <your@email.com>',
26 license: 'MIT',
27 repository: 'https://github.com/username/my-library',
28
29 // Entry points
30 entry: './src/index.ts',
31
32 // Output formats
33 formats: ['esm', 'cjs', 'umd'],
34
35 // External dependencies (not bundled)
36 externals: ['vue', 'react'],
37
38 // TypeScript declarations
39 dts: true,
40
41 // Minification
42 minify: true,
43
44 // Source maps
45 sourcemap: true,
46} satisfies LibraryConfig
47```
48
49### Package.json Configuration
50
51```json
52{
53 "name": "@yourscope/my-library",
54 "version": "1.0.0",
55 "description": "A useful library built with Stacks",
56 "type": "module",
57 "main": "./dist/index.cjs",
58 "module": "./dist/index.js",
59 "types": "./dist/index.d.ts",
60 "exports": {
61 ".": {
62 "import": "./dist/index.js",
63 "require": "./dist/index.cjs",
64 "types": "./dist/index.d.ts"
65 },
66 "./components": {
67 "import": "./dist/components/index.js",
68 "require": "./dist/components/index.cjs",
69 "types": "./dist/components/index.d.ts"
70 }
71 },
72 "files": [
73 "dist",
74 "README.md",
75 "LICENSE"
76 ],
77 "scripts": {
78 "build": "buddy build:lib",
79 "prepublishOnly": "bun run build"
80 },
81 "keywords": ["stacks", "typescript", "library"],
82 "author": "Your Name <your@email.com>",
83 "license": "MIT",
84 "repository": {
85 "type": "git",
86 "url": "git+https://github.com/username/my-library.git"
87 },
88 "publishConfig": {
89 "access": "public"
90 },
91 "peerDependencies": {
92 "vue": "^3.0.0"
93 }
94}
95```
96
97## Building Libraries
98
99### Build Command
100
101```bash
102# Build the library
103buddy build:lib
104
105# Build with watch mode
106buddy build:lib --watch
107
108# Build specific format
109buddy build:lib --format=esm
110```
111
112### Build Configuration
113
114```ts
115// buddy.config.ts
116import { defineConfig } from '@stacksjs/buddy'
117
118export default defineConfig({
119 library: {
120 // Entry file
121 entry: 'src/index.ts',
122
123 // Output directory
124 outDir: 'dist',
125
126 // Build formats
127 formats: ['esm', 'cjs'],
128
129 // External packages
130 external: [
131 'vue',
132 '@vue/*',
133 /^@stacksjs\//,
134 ],
135
136 // Global variable name for UMD builds
137 name: 'MyLibrary',
138
139 // Minification options
140 minify: {
141 mangle: true,
142 compress: {
143 drop*console: true,
144 },
145 },
146
147 // TypeScript configuration
148 typescript: {
149 declaration: true,
150 declarationDir: 'dist/types',
151 },
152 },
153})
154```
155
156### Multiple Entry Points
157
158```ts
159// config/library.ts
160export default {
161 entries: {
162 '.': './src/index.ts',
163 './components': './src/components/index.ts',
164 './utils': './src/utils/index.ts',
165 './composables': './src/composables/index.ts',
166 },
167}
168```
169
170## Versioning
171
172### Semantic Versioning
173
174```bash
175# Bump version
176buddy version patch # 1.0.0 -> 1.0.1
177buddy version minor # 1.0.0 -> 1.1.0
178buddy version major # 1.0.0 -> 2.0.0
179
180# Prerelease versions
181buddy version prepatch --preid=alpha # 1.0.0 -> 1.0.1-alpha.0
182buddy version preminor --preid=beta # 1.0.0 -> 1.1.0-beta.0
183buddy version premajor --preid=rc # 1.0.0 -> 2.0.0-rc.0
184
185# Prerelease increment
186buddy version prerelease # 1.0.0-alpha.0 -> 1.0.0-alpha.1
187```
188
189### Version Configuration
190
191```ts
192// config/release.ts
193export default {
194 // Automatically generate changelog
195 changelog: true,
196
197 // Commit message format
198 commitMessage: 'chore(release): v${version}',
199
200 // Tag format
201 tagFormat: 'v${version}',
202
203 // Files to update version in
204 files: [
205 'package.json',
206 'config/app.ts',
207 ],
208
209 // Git hooks
210 hooks: {
211 before: async () => {
212 await runTests()
213 await runLint()
214 },
215 after: async () => {
216 await buildDocs()
217 },
218 },
219}
220```
221
222### Changelog Generation
223
224```bash
225# Generate changelog
226buddy changelog
227
228# Preview changelog without writing
229buddy changelog --dry-run
230```
231
232## Publishing
233
234### NPM Publishing
235
236```bash
237# Publish to npm
238buddy publish
239
240# Publish with specific tag
241buddy publish --tag=beta
242
243# Publish to specific registry
244buddy publish --registry=https://npm.pkg.github.com
245
246# Dry run (don't actually publish)
247buddy publish --dry-run
248```
249
250### Authentication
251
252```bash
253# Login to npm
254npm login
255
256# For scoped packages
257npm login --scope=@yourscope
258
259# Set auth token (CI/CD)
260echo "//registry.npmjs.org/:*authToken=${NPM*TOKEN}" >> .npmrc
261```
262
263### Private Registry
264
265```ts
266// .npmrc
267@yourscope:registry=https://npm.pkg.github.com
268//npm.pkg.github.com/:*authToken=${GITHUB*TOKEN}
269```
270
271### GitHub Packages
272
273```json
274// package.json
275{
276 "name": "@username/my-library",
277 "publishConfig": {
278 "registry": "https://npm.pkg.github.com"
279 }
280}
281```
282
283## CI/CD Publishing
284
285### GitHub Actions
286
287```yaml
288# .github/workflows/publish.yml
289name: Publish
290
291on:
292 push:
293 tags:
294
295 - 'v*'
296
297jobs:
298 publish:
299 runs-on: ubuntu-latest
300 steps:
301
302 - uses: actions/checkout@v4
303
304 - name: Setup Bun
305
306 uses: oven-sh/setup-bun@v1
307
308 - name: Install dependencies
309
310 run: bun install
311
312 - name: Run tests
313
314 run: bun test
315
316 - name: Build
317
318 run: bun run build
319
320 - name: Publish to npm
321
322 run: npm publish
323 env:
324 NODE*AUTH*TOKEN: ${{ secrets.NPM*TOKEN }}
325```
326
327### Automated Release
328
329```yaml
330# .github/workflows/release.yml
331name: Release
332
333on:
334 push:
335 branches:
336
337 - main
338
339jobs:
340 release:
341 runs-on: ubuntu-latest
342 steps:
343
344 - uses: actions/checkout@v4
345
346 with:
347 fetch-depth: 0
348
349 - name: Setup Bun
350
351 uses: oven-sh/setup-bun@v1
352
353 - name: Install dependencies
354
355 run: bun install
356
357 - name: Create Release
358
359 run: bunx semantic-release
360 env:
361 GITHUB*TOKEN: ${{ secrets.GITHUB*TOKEN }}
362 NPM*TOKEN: ${{ secrets.NPM*TOKEN }}
363```
364
365## Documentation
366
367### Generating API Docs
368
369```bash
370# Generate TypeDoc documentation
371buddy docs:api
372
373# Serve docs locally
374buddy docs:serve
375```
376
377### TypeDoc Configuration
378
379```json
380// typedoc.json
381{
382 "entryPoints": ["src/index.ts"],
383 "out": "docs/api",
384 "name": "My Library",
385 "readme": "README.md",
386 "theme": "default",
387 "excludePrivate": true,
388 "excludeProtected": true,
389 "plugin": ["typedoc-plugin-markdown"]
390}
391```
392
393### README Template
394
395```markdown
396# My Library
397
398A brief description of what this library does.
399
400## Installation
401
402\`\`\`bash
403npm install @yourscope/my-library
404# or
405bun add @yourscope/my-library
406\`\`\`
407
408## Usage
409
410\`\`\`ts
411import { myFunction } from '@yourscope/my-library'
412
413const result = myFunction('hello')
414\`\`\`
415
416## API
417
418### myFunction(input: string): string
419
420Description of what the function does.
421
422**Parameters:**
423
424- `input` - Description of the input
425
426**Returns:** Description of the return value
427
428## License
429
430MIT
431```
432
433## Publishing Components
434
435### Vue Component Library
436
437```ts
438// src/index.ts
439import type { App } from 'vue'
440import MyButton from './components/MyButton.vue'
441import MyInput from './components/MyInput.vue'
442import MyModal from './components/MyModal.vue'
443
444export { MyButton, MyInput, MyModal }
445
446export default {
447 install(app: App) {
448 app.component('MyButton', MyButton)
449 app.component('MyInput', MyInput)
450 app.component('MyModal', MyModal)
451 },
452}
453```
454
455### Component Package.json
456
457```json
458{
459 "name": "@yourscope/components",
460 "version": "1.0.0",
461 "main": "./dist/index.cjs",
462 "module": "./dist/index.js",
463 "types": "./dist/index.d.ts",
464 "exports": {
465 ".": {
466 "import": "./dist/index.js",
467 "require": "./dist/index.cjs",
468 "types": "./dist/index.d.ts"
469 },
470 "./style.css": "./dist/style.css"
471 },
472 "sideEffects": ["*.css"],
473 "peerDependencies": {
474 "vue": "^3.3.0"
475 }
476}
477```
478
479## Publishing Functions
480
481### Function Library
482
483```ts
484// src/index.ts
485export { useDebounce } from './composables/useDebounce'
486export { useLocalStorage } from './composables/useLocalStorage'
487export { useAsync } from './composables/useAsync'
488export { formatDate, formatCurrency } from './utils/formatters'
489export { validateEmail, validatePhone } from './utils/validators'
490
491// Types
492export type { DebounceOptions } from './composables/useDebounce'
493export type { AsyncState } from './composables/useAsync'
494```
495
496## Pre-publish Checklist
497
498Before publishing, ensure:
499
5001. **Tests pass**
501
502 ```bash
503 bun test
504 ```
505
5062. **Types are correct**
507
508 ```bash
509 bun run typecheck
510 ```
511
5123. **Linting passes**
513
514 ```bash
515 bun run lint
516 ```
517
5184. **Build succeeds**
519
520 ```bash
521 bun run build
522 ```
523
5245. **Package contents are correct**
525
526 ```bash
527 npm pack --dry-run
528 ```
529
5306. **Version is correct**
531
532 ```bash
533 npm version patch
534 ```
535
5367. **Changelog is updated**
537
538 ```bash
539 buddy changelog
540 ```
541
542## Error Handling
543
544```ts
545try {
546 await publish()
547} catch (error) {
548 if (error.message.includes('403')) {
549 console.error('Not authorized to publish. Check npm login.')
550 } else if (error.message.includes('409')) {
551 console.error('Version already exists. Bump version first.')
552 } else if (error.message.includes('404')) {
553 console.error('Package not found. Check package name.')
554 } else {
555 console.error('Publish failed:', error.message)
556 }
557}
558```
559
560## Best Practices
561
5621. **Use semantic versioning** - Follow semver for predictable updates
5632. **Write good documentation** - Include README, API docs, and examples
5643. **Include TypeScript types** - Generate .d.ts files
5654. **Test before publishing** - Run tests in CI
5665. **Keep bundle size small** - Use tree-shaking, externalize dependencies
5676. **Maintain backwards compatibility** - Use deprecation warnings
568
569This documentation covers publishing packages and libraries from Stacks. Each step is designed for reliable and professional package distribution.