Development Workflow

Development Workflow

Guide for developers working on LARC itself or building applications with LARC.

---

Setting Up the Development Environment

Prerequisites

• Node.js >= 18.0.0
• Git

Initial Setup

# Clone the repository
git clone https://github.com/larcjs/larc.git
cd larc

# Install all dependencies (npm workspaces)
npm install

---

Repository Structure

larc/
├── packages/                   → Published packages (npm workspaces)
│   ├── core/                   → @larcjs/core
│   ├── components/             → @larcjs/ui
│   ├── core-lite/              → @larcjs/core-lite (9KB)
│   ├── core-routing/           → @larcjs/core-routing
│   ├── core-debug/             → @larcjs/core-debug
│   ├── core-types/             → TypeScript types
│   ├── components-types/       → TypeScript types
│   ├── apps/                   → Demo applications
│   ├── examples/               → Code examples
│   └── devtools/               → Chrome DevTools extension
├── cli/                        → create-larc-app
├── react-adapter/              → React integration
├── registry/                   → Component registry
├── vscode-extension/           → VS Code extension
├── docs/                       → Documentation & guides
└── playground/                 → Interactive component explorer

---

Development Workflows

Working on Core or Components

# Work on core
cd packages/core
npm install
npm run build
npm test

# Work on components
cd packages/ui
npm install
npm run build
npm test

Working on Packages

# Work on core-lite
cd packages/core-lite
npm run build:minify

# Work on types
cd packages/core-types
# Edit type definitions...

Using npm Workspaces

Run commands across all workspaces:

# Build all packages
npm run build

# Test all packages
npm run test

# Run specific workspace
npm run build --workspace @larcjs/core
npm run test --workspace @larcjs/ui
npm run dev --workspace @larcjs/site

---

Testing

Running Tests

# Test everything
npm test

# Test specific packages
npm run test:core
npm run test:components

# Test with coverage
cd packages/core
npm run test:coverage

Test Structure

Tests use Playwright for cross-browser testing:

# Run in all browsers
npx playwright test

# Run in specific browser
npx playwright test --project=chromium
npx playwright test --project=firefox
npx playwright test --project=webkit

---

Building

Build All Packages

npm run build

Build Specific Package

cd packages/core-lite
npm run build:minify

Documentation Site

# Build and serve docs
npm run dev --workspace @larcjs/site

# Or manually
cd site
npm run build
npm run serve

---

Running Examples

# Serve examples locally
cd packages/examples
python3 -m http.server 8888
# Visit http://localhost:8888

---

Publishing Packages

Packages are published to npm from the monorepo:

# Publish a specific package
cd packages/core-lite
npm publish

# Publish core or components
cd packages/core
npm publish

Pre-publish Checklist

• All tests passing
• Version bumped in package.json
• CHANGELOG.md updated
• No critical npm audit issues
• Build succeeds

---

Code Quality

Linting

npm run lint

Formatting

The project uses consistent formatting. Format before committing.

Type Checking

# Check TypeScript types
npm run typecheck

---

Git Workflow

Feature Development

# Create feature branch
git checkout -b feature/my-feature

# Make changes
# ...

# Commit with clear message
git add .
git commit -m "feat: add new feature"

# Push and create PR
git push origin feature/my-feature

Commit Message Format

Follow conventional commits:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation
• refactor: - Code refactoring
• test: - Tests
• chore: - Maintenance

---

Launch Checklist

1 Week Before Launch

Repository & Code:

• All tests passing (261+ core tests)
• No critical npm audit issues
• Latest versions published to npm
• GitHub Actions workflows all green

Documentation:

• README.md up to date
• API documentation complete
• CHANGELOG.md updated
• All links verified working

Examples & Demos:

• Playground working
• All examples tested
• Mobile responsiveness verified

Day Before Launch

Final Testing:

• Test on Chrome, Firefox, Safari, Edge
• Test on mobile (iOS Safari, Chrome Android)
• Clone fresh repo and follow Quick Start
• Install from npm and verify it works

Performance Check:

• Playground loads in <3 seconds
• No console errors on any page
• No 404s in network tab

Launch Day

• All services up (GitHub, npm, CDN)
• Team members available
• Notifications enabled for issues
• FAQ answers ready

---

Debugging During Development

Enable Debug Mode

<pan-bus debug="true"></pan-bus>

Use Pan Inspector

<pan-inspector></pan-inspector>

Check Bus Statistics

document.dispatchEvent(new CustomEvent('pan:sys.stats', {
  bubbles: true,
  composed: true
}));

---

Contributing

Getting Started

1. Fork the repository
2. Clone your fork
3. Install dependencies: npm install
4. Create feature branch
5. Make changes and add tests
6. Test: npm test
7. Submit pull request

Code Review Process

• PRs require at least one approval
• CI must pass
• Tests must cover new code
• Documentation must be updated

---

Resources

• API-Reference - Full API documentation
• Troubleshooting - Common issues
• GitHub Issues - Report bugs
• GitHub Discussions - Ask questions

---

Available Scripts

Script	Description
npm run build	Build all workspace packages
npm run test	Run tests across all packages
npm run dev	Start development mode
npm run lint	Lint all packages
npm run serve	Serve examples on port 8000
npm run build:core	Build only @larcjs/core
npm run build:components	Build only @larcjs/ui
npm run test:core	Test only @larcjs/core
npm run dev:site	Run documentation site