{"id":30017348,"url":"https://github.com/john-pels/monorepo-template","last_synced_at":"2026-04-29T08:34:40.430Z","repository":{"id":306742188,"uuid":"1026488681","full_name":"John-pels/monorepo-template","owner":"John-pels","description":"This monorepo template provides a robust foundation for building scalable, multi-package JavaScript and TypeScript projects.","archived":false,"fork":false,"pushed_at":"2025-07-27T13:11:13.000Z","size":4385,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-05T22:56:21.457Z","etag":null,"topics":["biomejs","bun","monorepo","nextjs","tanstack-router","turborepo","typescript","vitejs"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/John-pels.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-26T01:58:27.000Z","updated_at":"2025-07-30T09:54:01.000Z","dependencies_parsed_at":"2025-07-27T11:40:26.034Z","dependency_job_id":null,"html_url":"https://github.com/John-pels/monorepo-template","commit_stats":null,"previous_names":["john-pels/monorepo-template"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/John-pels/monorepo-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/John-pels%2Fmonorepo-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/John-pels%2Fmonorepo-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/John-pels%2Fmonorepo-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/John-pels%2Fmonorepo-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/John-pels","download_url":"https://codeload.github.com/John-pels/monorepo-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/John-pels%2Fmonorepo-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32417969,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T06:29:02.080Z","status":"ssl_error","status_checked_at":"2026-04-29T06:29:00.631Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["biomejs","bun","monorepo","nextjs","tanstack-router","turborepo","typescript","vitejs"],"created_at":"2025-08-05T22:56:12.078Z","updated_at":"2026-04-29T08:34:40.414Z","avatar_url":"https://github.com/John-pels.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Monorepo Template\n\nThis monorepo template provides a robust foundation for building scalable, multi-package JavaScript and TypeScript projects. It leverages Yarn Workspaces and Turborepo to streamline dependency management, build processes, and development workflows. Designed for front-end and back-end applications, this template supports React for UI development, Node.js for server-side logic, and shared utility packages for code reuse across projects\n\n## 🚀 Features\n\n- **Unified Workspace Management**: Streamlined development across multiple packages and applications\n- **Dependency Management**: Centralized package management with workspace-aware installations\n- **Build Orchestration**: Intelligent build caching and parallel execution\n- **Code Quality**: Integrated linting, formatting, and testing workflows\n- **CI/CD Ready**: Pre-configured pipelines for automated testing and deployment\n- **Developer Experience**: Hot reload, type checking, and debugging capabilities\n- **Scalable Architecture**: Modular structure supporting both libraries and applications\n\n## 📁 Repository Structure\n\n```\nmonorepo-template/\n├── .github/                    # GitHub workflows and templates\n│   ├── workflows/\n│   │   ├── ci.yml             # Continuous integration pipeline\n│   │   ├── release.yml        # Release automation\n│   │   └── pr-checks.yml      # Pull request validation\n│   └── PULL_REQUEST_TEMPLATE.md\n├── .vscode/                    # VS Code workspace configuration\n│   ├── extensions.json        # Recommended extensions\n│   ├── settings.json          # Workspace settings\n│   └── launch.json           # Debug configuration\n├── apps/                       # Application packages\n│   ├── web/          # Frontend web application with Next.js\n│   ├── dashboard/   # Admin dashboard web application with Tanstack Router powered by Vite\n│   └── mobile/                # Mobile application\n├── packages/                   # Shared library packages\n│   ├── ui/                    # Shared UI components\n│   ├── utils/\n    ├── eslint-config/         # Shared ESLint configuration\n│   ├── jest-config/           # Testing configuration             # Utility functions\n│   ├── config/                # Configuration presets\n│   └── types/                 # TypeScript definitions\n├── docs/                       # Documentation\n│   ├── architecture.md        # System architecture overview\n│   ├── contributing.md        # Contribution guidelines\n│   └── deployment.md          # Deployment instructions\n├── .biomejs.json               # Biome configuration for linting and formatting\n├── .eslintrc.js               # ESLint configuration (if using alongside Biome)\n├── .gitignore                 # Git ignore patterns\n├── .nvmrc                     # Node.js version specification\n├── commitlint.config.js       # Commitlint configuration\n├── jest.config.js             # Jest testing configuration\n├── package.json               # Root package configuration\n├── tsconfig.json              # TypeScript configuration\n├── turbo.json                 # Turborepo configuration\n└── bun.lockb               # Dependency lock file\n```\n\n## 🛠 Prerequisites\n\nEnsure your development environment meets these requirements:\n\n- **Node.js**: v18.0.0 or higher\n- **Package Manager**: Bun (preferred) or Yarn v3+ or npm v8+\n- **Git**: v2.30.0 or higher\n\n## Package Manager Setup\n\n```bash\n#inside the package.json, add this:\n \"packageManager\": \"bun@1.2.19\",\n\n# Or this for yarn\n  \"packageManager\": \"yarn@1.22.22\",\n\n# Or this or npm\n  \"packageManager\": \"npm@10.9.0\",\n```\n\n## 📋 Dependencies Installation\n\n### Core Development Dependencies\n\nInstall the essential development dependencies for code quality, git hooks, and commit management:\n\n```bash\n# Install Biome for code quality, linting and formatting\nbun add -D @biomejs/biome\n\n# Install Husky for git hooks\nbun add -D husky\n\n# Install lint-staged for running linters on staged files\nbun add -D lint-staged\n\n# Install Commitlint for commit message validation\nbun add -D @commitlint/cli @commitlint/config-conventional\n```\n\n### Setup Commands\n\nAfter installing dependencies, run these setup commands:\n\n```bash\n# Initialize Husky\nnpx husky init\n\n# Create Biome configuration\nnpx @biomejs/biome init\n\n# Setup git hooks\necho \"npx lint-staged\" \u003e .husky/pre-commit\necho \"npx commitlint --edit \\$1\" \u003e .husky/commit-msg\n\n# Make hooks executable\nchmod +x .husky/pre-commit\nchmod +x .husky/commit-msg\n```\n\n## ⚡ Quick Start\n\n### 1. Repository Setup\n\n```bash\n# Clone the template\ngit clone https://github.com/John-pels/monorepo-template.git your-project-name\ncd your-project-name\n\n# Remove existing git history and initialize fresh repository\nrm -rf .git\ngit init\ngit add .\ngit commit -m \"Initial commit from monorepo template\"\n```\n\n### 2. Environment Configuration\n\n```bash\n# Install dependencies\nbun install\n\n# Copy environment template\ncp .env.example .env\n\n# Configure Node.js version\nnvm use\n```\n\n### 3. Development Workflow\n\n```bash\n# Start all applications in development mode\nbun dev\n\n# Start a specific application in development mode\nbun dev --filter=app-name # For instance, bun dev --filter=web\n\n# Run specific application\nbun workspace @your-org/web dev\nbun workspace @your-org/api dev\n\n# Build all packages\nbun run build\n\n# Run tests across all packages\nbun run test\n\n# Lint codebase\nbun run lint\n\n# Fix linting and formatting issues\nbun format-and-lint:fix\n\n# Format code\nbun run format\n\n# Check for typescript error without writing\nbun run check-types\n\n# watchout for typescript error without writing\nbun run check-types:watch\n```\n\n## 📦 Package Management\n\n### Adding Dependencies\n\n```bash\n# Add dependency to specific workspace\nbun workspace @your-org/web add react react-dom\nbun workspace @your-org/api add express\n\n# Add dev dependency to root\nbun add -D typescript @types/node\n\n# Add dependency to multiple workspaces\nbun workspaces foreach add lodash\n```\n\nFor each application in the `apps/` folder,we add `\"@repo/ui\": \"*\",` to the dependencies in the app `package.json` file and\n\n- also add the `\"@repo/eslint-config\": \"*\",` and `\"@repo/typescript-config\": \"*\",` to the `devDependencies` in the `package.json` file. Do the same for every new package you add to the `packages/` folder.\n\n### Creating New Application and Packages\n\n```bash\n# Create new application\ncd apps/\n\n# To create a new Next.js application, then run the below command\nnpx create-next-app@latest\n\n# To create a new web application with Vite.js, run the below command and follow the prompts\nnpm create vite@latest\n\n# Create new shared package\nmkdir packages/auth\ncd packages/auth\nbun init -y\n```\n\n**NOTE**: Just as UI is for anything user interface or components, shared providers such as Tanstack Query, Chakra UI, Zustand, HTTP clients, etc can be added inside this package and used across the applications. See this packages folder as a place where you can create local NPM packages and use them anywhere in this monorepo.\n\n**\\*Also**, it is super important to use different port for all the applications in the `package.json` . For instance, we have two applications in the `apps/` folder.\n\n- For the `web` application, we will use port `8000`\n- For the `dashboard` application, we will use port `8001`.\n\n### Workspace Dependencies\n\nReference internal packages in root `package.json`:\n\n```json\n \"workspaces\": [\"apps/*\", \"packages/*\"],\n```\n\n## 🏗 Build System\n\n### Build Configuration\n\nThe monorepo uses Turborepo for efficient build orchestration:\n\n```json\n{\n  \"pipeline\": {\n    \"build\": {\n      \"dependsOn\": [\"^build\"],\n      \"outputs\": [\"dist/**\", \".next/**\"]\n    },\n    \"test\": {\n      \"dependsOn\": [\"build\"],\n      \"inputs\": [\"src/**\", \"test/**\"]\n    },\n    \"lint\": {\n      \"outputs\": []\n    }\n  }\n}\n```\n\n### Build Commands\n\n```bash\n# Build with caching\nbun run build\n\n# Build a soecific app with caching\nbun run build --filter=app-name # For instance, bun run build --filter=web\n\n# Build specific package and its dependencies\nbun workspace @your-org/web build\n\n# Clear build cache\nbun build --force\n\n# Build with verbose output\nbun build --verbose\n```\n\n## 🧪 Testing Strategy\n\n### Test Structure\n\n- **Unit Tests**: Individual function and component testing\n- **Integration Tests**: Cross-package interaction validation\n- **E2E Tests**: Full application workflow testing\n\n### Running Tests\n\n```bash\n# Run all tests\nbun test\n\n# Run tests in watch mode\nbun test --watch\n\n# Run tests with coverage\nbun test --coverage\n\n# Run tests for specific package\nbun workspace @your-org/utils test\n```\n\n### Test Configuration\n\nJest configuration supports multiple testing environments:\n\n```javascript\nmodule.exports = {\n  projects: [\n    {\n      displayName: \"web\",\n      testEnvironment: \"jsdom\",\n      testMatch: [\"\u003crootDir\u003e/apps/web/**/*.test.{js,ts,tsx}\"],\n    },\n    {\n      displayName: \"api\",\n      testEnvironment: \"node\",\n      testMatch: [\"\u003crootDir\u003e/apps/api/**/*.test.{js,ts}\"],\n    },\n  ],\n};\n```\n\n## 🔧 Code Quality\n\n### Biome Configuration\n\nCreate a `biome.json` configuration file:\n\n```json\n{\n  \"$schema\": \"https://biomejs.dev/schemas/1.8.3/schema.json\",\n  \"vcs\": {\n    \"enabled\": true,\n    \"clientKind\": \"git\",\n    \"useIgnoreFile\": true\n  },\n  \"organizeImports\": {\n    \"enabled\": true\n  },\n  \"linter\": {\n    \"enabled\": true,\n    \"ignore\": [\"./apps/dashboard/src/routeTree.gen.ts\"],\n    \"rules\": {\n      \"recommended\": true,\n      \"correctness\": {\n        \"noUnusedVariables\": \"error\",\n        \"noUnusedImports\": \"error\"\n      },\n      \"security\": {\n        \"noDangerouslySetInnerHtml\": \"off\"\n      },\n      \"suspicious\": {\n        \"noConsoleLog\": \"warn\"\n      },\n      \"a11y\": {\n        \"noSvgWithoutTitle\": \"off\"\n      }\n    }\n  },\n  \"formatter\": {\n    \"enabled\": true,\n    \"lineWidth\": 80,\n    \"indentStyle\": \"space\",\n    \"indentWidth\": 2,\n    \"lineEnding\": \"lf\",\n    \"formatWithErrors\": false\n  },\n  \"javascript\": {\n    \"formatter\": {\n      \"semicolons\": \"asNeeded\",\n      \"trailingCommas\": \"es5\",\n      \"quoteStyle\": \"single\",\n      \"arrowParentheses\": \"always\",\n      \"bracketSameLine\": false,\n      \"bracketSpacing\": true,\n      \"jsxQuoteStyle\": \"double\",\n      \"quoteProperties\": \"asNeeded\"\n    }\n  },\n  \"json\": {\n    \"formatter\": {\n      \"trailingCommas\": \"none\"\n    },\n    \"parser\": {\n      \"allowComments\": true\n    }\n  }\n}\n```\n\n### Linting, Formatting and Code Quality Commands\n\n```bash\n# Check code with Biome (linting + formatting)\nbun biome check .\n\n# Fix linting and formatting issues\nbun biome check --apply .\n\n# Format code only\nbun biome format --write .\n\n# Lint code only\nbun biome lint .\n\n# Fix linting issues only\nbun biome lint --apply .\n\n# Organize imports\nbun biome check --apply-unsafe .\n```\n\n### Git Hooks Configuration\n\nCreate a `commitlint.config.js` file:\n\n```javascript\nmodule.exports = {\n  extends: [\"@commitlint/config-conventional\"],\n  rules: {\n    \"body-leading-blank\": [1, \"always\"],\n    \"body-max-line-length\": [2, \"always\", 100],\n    \"footer-leading-blank\": [1, \"always\"],\n    \"footer-max-line-length\": [2, \"always\", 100],\n    \"header-max-length\": [2, \"always\", 100],\n    \"scope-case\": [2, \"always\", \"lower-case\"],\n    \"subject-case\": [\n      2,\n      \"never\",\n      [\"sentence-case\", \"start-case\", \"pascal-case\", \"upper-case\"],\n    ],\n    \"subject-empty\": [2, \"never\"],\n    \"subject-full-stop\": [2, \"never\", \".\"],\n    \"type-case\": [2, \"always\", \"lower-case\"],\n    \"type-empty\": [2, \"never\"],\n    \"type-enum\": [\n      2,\n      \"always\",\n      [\n        \"build\",\n        \"chore\",\n        \"ci\",\n        \"docs\",\n        \"feat\",\n        \"fix\",\n        \"perf\",\n        \"refactor\",\n        \"revert\",\n        \"style\",\n        \"test\",\n        \"translation\",\n        \"security\",\n        \"changeset\",\n      ],\n    ],\n  },\n};\n```\n\n### Package.json Scripts\n\nAdd these scripts to your root `package.json`:\n\n```json\n{\n  \"scripts\": {\n    \"build\": \"turbo run build\",\n    \"dev\": \"dotenv -- turbo run dev\",\n    \"lint\": \"biome check --write --unsafe\",\n    \"format\": \"prettier --write \\\"**/*.{ts,tsx,md}\\\"\",\n    \"format-and-lint:fix\": \"biome check --write --unsafe\",\n    \"prepare\": \"husky\",\n    \"knip\": \"knip\",\n    \"check-types\": \"turbo run check-types\",\n    \"check-types:watch\": \"turbo run check-types:watch\"\n  }\n}\n```\n\n### Pre-commit Hooks\n\nConfigure lint-staged in your `package.json`:\n\n```json\n{\n  \"lint-staged\": {\n    \"*.{js,jsx,ts,tsx,json}\": [\"biome check --apply --no-errors-on-unmatched\"],\n    \"*.{md,yml,yaml}\": [\"biome format --write --no-errors-on-unmatched\"]\n  }\n}\n```\n\n### Environment Variables\n\nConfigure environment-specific variables:\n\n```bash\n# Development\nNODE_ENV=development\nAPI_URL=http://localhost:3001\n\n# Production\nNODE_ENV=production\nAPI_URL=https://api.yourdomain.com\n```\n\n## 🔄 CI/CD Pipeline\n\n### GitHub Actions Workflow\n\nThe repository includes automated workflows for:\n\n- **Continuous Integration**: Automated testing on pull requests\n- **Dependency Updates**: Automated dependency management\n- **Release Management**: Semantic versioning and changelog generation\n- **Deployment**: Automated deployment to staging and production\n\n### Pipeline Configuration\n\n```yaml\nname: CI\non: [push, pull_request]\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n      - uses: actions/setup-node@v3\n        with:\n          node-version: \"18\"\n          cache: \"yarn\"\n      - run: yarn install --frozen-lockfile\n      - run: yarn lint\n      - run: yarn test\n      - run: yarn build\n```\n\n## 🤝 Contributing\n\n### Development Workflow\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Make your changes following the coding standards\n4. Add tests for new functionality\n5. Run the full test suite: `bun test`\n6. Commit using conventional commits: `git commit -m \"feat: add amazing feature\"`\n7. Push to your branch: `git push origin feature/amazing-feature`\n8. Open a Pull Request\n\n### Commit Convention\n\nFollow conventional commits for automated changelog generation. The commitlint configuration enforces these rules:\n\n- `feat:` New features\n- `fix:` Bug fixes\n- `docs:` Documentation changes\n- `style:` Code style changes (formatting, missing semicolons, etc)\n- `refactor:` Code refactoring without changing functionality\n- `perf:` Performance improvements\n- `test:` Test additions or modifications\n- `build:` Build system or external dependency changes\n- `ci:` CI/CD configuration changes\n- `chore:` Maintenance tasks and other changes\n- `revert:` Reverting previous commits\n\n**Commit Message Format:**\n\n```\n\u003ctype\u003e[optional scope]: \u003cdescription\u003e\n\n[optional body]\n\n[optional footer(s)]\n```\n\n**Examples:**\n\n```bash\ngit commit -m \"feat: add user authentication system\"\ngit commit -m \"fix(api): resolve login endpoint timeout issue\"\ngit commit -m \"docs: update installation instructions\"\ngit commit -m \"style: format code with biome\"\n```\n\n## 📚 Documentation\n\n- [Architecture Overview](./docs/architecture.md)\n- [API Documentation](./docs/api.md)\n- [Deployment Guide](./docs/deployment.md)\n- [Contributing Guidelines](./docs/contributing.md)\n- [Troubleshooting](./docs/troubleshooting.md)\n\n## 🛡 Security\n\n### Security Practices\n\n- Regular dependency audits with `bun audit`\n- Automated vulnerability scanning in CI/CD\n- Environment variable validation\n- Input sanitization and validation\n- HTTPS enforcement in production\n\n## 📊 Performance\n\n### Optimization Features\n\n- **Build Caching**: Turborepo intelligent caching\n- **Code Splitting**: Automatic bundle optimization\n- **Tree Shaking**: Dead code elimination\n- **Asset Optimization**: Image and font optimization\n- **CDN Integration**: Static asset delivery optimization\n\n## 🔍 Troubleshooting\n\n### Common Issues\n\n**Installation Problems**\n\n```bash\n# Clear cache and reinstall\nbun cache clean\nrm -rf node_modules yarn.lock\nbun install\n```\n\n**Find and Fix Unused Dependencies, Exports, and File**\n\n```bash\nbun run knip\n```\n\n**Build Failures**\n\n```bash\n# Check TypeScript errors\nbun run check-types\n\n# Clear build cache\nbun run build --force\n```\n\n**Test Issues**\n\n```bash\n# Clear Jest cache\nbun test --clearCache\n\n# Run tests in debug mode\nbun test --verbose\n```\n\n## 📄 License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Turborepo](https://turbo.build/) for build orchestration\n- [Bun](https://bun.com/docs) for package management\n- [Next.js](https://nextjs.org/) for creating next.js application\n- [Vite.js](https://vite.dev/guide/) for creating vite powered application.\n- [TypeScript](https://www.typescriptlang.org/) for type safety\n- [Jest](https://jestjs.io/) for testing framework\n- [Biome](https://biomejs.dev/) for code linting and formatting\n- [Husky](https://typicode.github.io/husky/) for git hooks\n- [Commitlint](https://commitlint.js.org/) for commit message validation\n\n## 📞 Support\n\n- 📖 [Documentation](./docs/documentation.md)\n- 🐛 [Issue Tracker](https://github.com/John-pels/monorepo-template/issues)\n- 💬 [Discussions](https://github.com/John-pels/monorepo-template/discussions)\n- 📧 [Email Support](johnoluemmanuel@gmail.com)\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohn-pels%2Fmonorepo-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohn-pels%2Fmonorepo-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohn-pels%2Fmonorepo-template/lists"}