bytelyst/learning_ai_invt_trdg
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add local package resolution section to UX guide

Browse Source 
Added critical section on using local common platform packages instead of Gitea registry:

- .pnpmfile.cjs configuration for local package resolution
- .npmrc configuration (remove repo-level GITEA_NPM_TOKEN)
- Environment variables (BYTELYST_PACKAGE_SOURCE)
- Verification commands to confirm local resolution
- Benefits of local package resolution (faster dev, offline, no registry dependency)
- Updated Phase 1 roadmap to include local package setup

This ensures other products follow the same approach of using local common-plat packages by default instead of pulling from Gitea registry.
This commit is contained in:
Saravana Achu Mac 2026-05-09 14:21:46 -07:00
parent 691d8aa9da
commit e87d7a5839
1 changed files with 82 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

83
docs/UX_TESTING_SETUP_GUIDE.md
View File

@ -22,6 +22,80 @@ This guide documents the complete UX implementation approach for the trading das
## Part 1: Common Platform UI Integration
### Local Package Resolution
**Critical:** Use local common platform packages by default, not Gitea registry.
**File:** `.pnpmfile.cjs`
```javascript
// .pnpmfile.cjs
// Default to local common platform packages
function readPackage(pkg, context) {
if (!context.workspace) return pkg;
// Default to common-plat (local packages)
const packageSource = process.env.BYTELYST_PACKAGE_SOURCE || 'common-plat';
if (packageSource === 'common-plat') {
// Resolve @bytelyst/* packages from local common platform
if (pkg.name.startsWith('@bytelyst/')) {
pkg.dependencies = pkg.dependencies || {};
pkg.dependencies[pkg.name] = 'workspace:*';
}
}
return pkg;
}
module.exports = {
name: 'bytelyst-package-source',
hooks: {
readPackage,
},
};
```
**File:** `.npmrc`
```ini
# Remove repo-level GITEA_NPM_TOKEN interpolation
# Gitea registry auth should live in user-level ~/.npmrc or CI secrets
# Only when BYTELYST_PACKAGE_SOURCE=gitea is explicitly used
```
**Commit Reference:** `f2216ad` - chore(pnpm): prefer local bytelyst packages
### Environment Variables
```bash
# Default: Use local common platform packages
BYTELYST_PACKAGE_SOURCE=common-plat
# Optional: Use Gitea registry (requires auth)
BYTELYST_PACKAGE_SOURCE=gitea
# GITEA_NPM_TOKEN should be in ~/.npmrc or CI secrets
```
### Verification Commands
```bash
# Verify local package resolution
pnpm install @bytelyst/ui @bytelyst/design-tokens
# Verify packages resolve from local common platform
pnpm list @bytelyst/ui
# Should show: @bytelyst/ui -> link:../learning_ai_common_plat/packages/ui
```
### Benefits of Local Package Resolution
1. **Faster Development** - No network calls to registry during development
2. **Immediate Updates** - Changes to common platform are immediately available
3. **No Registry Dependency** - Works offline and without Gitea access
4. **Consistent Builds** - Same packages across all environments
5. **Simpler CI** - No need for registry auth in CI by default
### Product Adapter Pattern
Create a product adapter to normalize imports and extend shared primitives with product-specific variants:
@ -1014,7 +1088,9 @@ const statusColors = {
### Phase 1: Foundation Setup
**Week 1-2**
- [ ] Install common platform packages
- [ ] Set up local package resolution (.pnpmfile.cjs)
- [ ] Remove repo-level GITEA_NPM_TOKEN from .npmrc
- [ ] Install common platform packages from local source
- [ ] Create product adapter (`Primitives.tsx`)
- [ ] Set up design token integration
- [ ] Configure Playwright
@ -1022,7 +1098,12 @@ const statusColors = {
**Verification:**
```bash
# Verify local package resolution
pnpm install @bytelyst/ui @bytelyst/design-tokens
pnpm list @bytelyst/ui
# Should show: @bytelyst/ui -> link:../learning_ai_common_plat/packages/ui
# Verify build works with local packages
pnpm run typecheck
pnpm run build
```