Developer Guide - Dual Release System

> Note: This is the developer documentation. For end-user documentation, see README.md

🎯 Overview

This repository maintains a single codebase that publishes to two separate NPM packages:

- @tawasal/node - Tawasal-branded SDK
- @nija/node - Nija-branded SDK (no Tawasal references)

🏗️ Architecture

``
Single Codebase (src/)
│
├─────────────────┬─────────────────┐
│ │ │
▼ ▼ ▼
Source Code README Files Workflows
│ │ │
│ ┌──────┴──────┐ │
│ │ │ │
▼ ▼ ▼ ▼
dist/ README.tawasal README.nija GitHub Actions
│ │ │ │
└──────────┴─────────────┴─────────┘
│
┌───────────┴───────────┐
│ │
▼ ▼
@tawasal/node @nija/node
(NPM Package) (NPM Package)
`

📦 What Gets Published

$3


- ✅ Same source code (src/)
- ✅ Same compiled output (dist/)
- ✅ Same version number
- ✅ Same functionality

$3

- ❌ Package name (@tawasal/node vs @nija/node)
- ❌ README content (branding)
- ❌ NPM account/token
- ❌ Git tags (-tawasal vs -nija suffix)

🚀 How to Release

$3

#### Tawasal Release
1. Navigate to Actions tab
2. Select "Publish Tawasal" workflow
3. Click "Run workflow"
4. Select version bump: major | minor | patch
5. Click "Run workflow" button

#### Nija Release
1. Navigate to Actions tab
2. Select "Publish Nija" workflow
3. Click "Run workflow"
4. Select version bump: major | minor | patch
5. Click "Run workflow" button

$3

`bash


Switch README

npm run readme:tawasal # Switch to Tawasal README
npm run readme:nija # Switch to Nija README

Build

npm run build

Lint

npm run lint
`

🔧 Development Workflow

$3

`bash


1. Create feature branch

git checkout -b feature/my-feature

2. Make changes to source code

vim src/tawasal.ts

3. Update BOTH README files

vim README.tawasal.md # Add Tawasal-specific docs
vim README.nija.md # Add Nija-specific docs (no Tawasal refs)

4. Test locally

npm run build
npm run lint

5. Commit and push

git add .
git commit -m "feat: add new feature"
git push origin feature/my-feature

6. Create PR and merge to main

`

$3

`bash


After PR is merged to main:

Option A: Release both packages

1. Run "Publish Tawasal" workflow (patch)
2. Run "Publish Nija" workflow (patch)

Option B: Release only one package

1. Run only the needed workflow

Result:

@tawasal/node@X.X.X published

@nija/node@X.X.X published

`

📝 README Management

$3

`
README.md ← Active README (swapped during release)
README.tawasal.md ← Tawasal version (source of truth for Tawasal)
README.nija.md ← Nija version (source of truth for Nija)
README.DEVELOPERS.md ← This file (for developers)
`

$3

1. Never edit README.md directly - it gets overwritten
2. Always update both README.tawasal.md and README.nija.md
3. Keep shared sections synchronized
4. Remove Tawasal references from README.nija.md

$3

`bash


1. Add to Tawasal README

cat >> README.tawasal.md << 'EOF'

New Feature

This feature works with Tawasal SuperApp...

`javascript
import { newFeature } from '@tawasal/node';
`
EOF

2. Add to Nija README (without Tawasal references)

cat >> README.nija.md << 'EOF'

New Feature

This feature works with Nija SuperApp...

`javascript
import { newFeature } from '@nija/node';
`
EOF

3. Commit both


git add README.*.md
git commit -m "docs: add new feature documentation"
`

🔐 Secrets Configuration

$3

| Secret Name | Purpose | How to Get |
|-------------|---------|------------|
| NPM_TOKEN | Publish @tawasal/node | npm login (Tawasal account) → npm token create --type=automation |
| NIJA_NPM_TOKEN | Publish @nija/node | npm login (Nija account) → npm token create --type=automation |

$3

1. Go to Repository Settings
2. Navigate to Secrets and variables → Actions
3. Click "New repository secret"
4. Add each secret with its value

🧪 Testing

$3

`bash


Install dependencies

npm install

Build

npm run build

Verify output

ls -la dist/
cat dist/index.d.ts
`

$3

`bash


Test Tawasal README

npm run readme:tawasal
head -n 10 README.md | grep -i tawasal

Test Nija README

npm run readme:nija
head -n 10 README.md | grep -i nija

Restore to Tawasal (default)

npm run readme:tawasal
`

$3

`bash


Simulate Nija package.json update

node -e "
const fs = require('fs');
const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
console.log('Before:', pkg.name);
pkg.name = '@nija/node';
console.log('After:', pkg.name);
fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2));
"

Verify

cat package.json | grep '"name"'

Restore

git checkout package.json
`

📊 Version Management

$3

- Patch (X.X.1): Bug fixes, documentation updates
- Minor (X.1.0): New features, backward compatible
- Major (1.0.0): Breaking changes

$3

Both packages share the same version number:

`
@tawasal/node@1.2.3
@nija/node@1.2.3
`

But have separate git tags:

`
v1.2.3-tawasal
v1.2.3-nija
`

$3

`bash


Current version: 1.0.0

Release patch to both

1. Publish Tawasal (patch) → v1.0.1-tawasal → @tawasal/node@1.0.1
2. Publish Nija (patch) → v1.0.1-nija → @nija/node@1.0.1

Release minor to both

1. Publish Tawasal (minor) → v1.1.0-tawasal → @tawasal/node@1.1.0
2. Publish Nija (minor) → v1.1.0-nija → @nija/node@1.1.0
`

🐛 Troubleshooting

$3

Solution:
1. Check workflow logs in Actions tab
2. Verify secrets are configured
3. Check NPM token hasn't expired
4. Try manual release (see DUAL_RELEASE_GUIDE.md)

$3

Solution:
`bash


Trigger new release with correct README

The workflow will automatically use the right README

`

$3

Solution:
`bash


Check current version

npm version

Reset if needed

npm version 1.0.0 --no-git-tag-version
git add package.json package-lock.json
git commit -m "chore: reset version"
git push
`

$3

Solution:
`bash


The workflow automatically restores it

If manual fix needed:

git checkout package.json
git push
`

📚 Documentation Files

| File | Purpose | Audience |
|------|---------|----------|
| README.md | Active README (swapped) | End users |
| README.tawasal.md | Tawasal README source | End users (Tawasal) |
| README.nija.md | Nija README source | End users (Nija) |
| README.DEVELOPERS.md | This file | Developers |
| DUAL_RELEASE_SUMMARY.md | Quick start guide | Developers |
| DUAL_RELEASE_GUIDE.md | Complete guide | Developers |
| RELEASE_CHECKLIST.md | Release checklist | Release managers |
| ARCHITECTURE.md | System architecture | Developers/DevOps |
| REFRESH_TOKEN_GUIDE.md | Refresh token docs | End users |

🎓 Best Practices

1. Always test locally before releasing
2. Update both READMEs when adding features
3. Use semantic versioning consistently
4. Keep versions synchronized between packages
5. Document breaking changes clearly
6. Test both packages after release
7. Monitor NPM downloads for both packages
8. Review GitHub Actions logs regularly

🔄 Maintenance Tasks

$3


- [ ] Check GitHub Actions for failed workflows
- [ ] Review NPM download stats
- [ ] Check for security vulnerabilities: npm audit

$3

- [ ] Update dependencies: npm update
- [ ] Review and update documentation
- [ ] Check NPM token expiration dates

$3

- [ ] Review and update README files
- [ ] Audit GitHub secrets
- [ ] Review version strategy

🆘 Emergency Procedures

$3

`bash


Unpublish specific version


npm unpublish @tawasal/node@1.0.0
npm unpublish @nija/node@1.0.0
`

$3

`bash


Deprecate version


npm deprecate @tawasal/node@1.0.0 "Use version 1.0.1 instead"
npm deprecate @nija/node@1.0.0 "Use version 1.0.1 instead"
`

$3

`bash


1. Deprecate bad version

npm deprecate @tawasal/node@1.0.1 "Critical bug, use 1.0.0"

2. Release fixed version

Use GitHub Actions to release 1.0.2

``

📞 Support

- Tawasal Package Issues: tawasal-team@example.com
- Nija Package Issues: nija-team@example.com
- CI/CD Issues: devops@example.com
- General Questions: Check documentation first

🔗 Useful Links

- NPM - @tawasal/node
- NPM - @nija/node
- GitHub Actions
- Repository Settings

---

Last Updated: 2025-08-07
Maintained By: Development Team