A modern React monorepo showcasing Next.js 15, TypeScript, and best practices for enterprise development. Features internationalization, authentication, theming, and a comprehensive design system.
- Node.js: Version specified in
package.json - pnpm: Version specified in
package.json - Corepack: Run
corepack enableto manage package manager versions automatically - Docker: For containerized development (optional but recommended)
# Clone, install, and start development
git clone <repository-url>
cd JS-React-Example
pnpm install && pnpm devAccess the applications:
- Frontend: http://localhost:3000
- Storybook: http://localhost:6006
The application uses NextAuth.js with multiple providers:
- Development: Uses mock authentication - any email/password combination works
- Production: Configure OAuth providers (Google, GitHub) via environment variables
No additional setup required for local development - authentication is pre-configured for immediate use.
This monorepo leverages Next.js 15's App Router with modern React patterns. The frontend uses Server Components for optimal performance, Route Handlers for API endpoints, and Edge Runtime middleware for authentication. Internationalization runs at the routing level with locale-aware navigation, while the design system provides consistent theming across light/dark modes. The component library uses composition patterns with CVA variants, enabling rapid UI development with type safety throughout.
apps/
├── frontend/ # Next.js application (main app)
└── storybook/ # Component documentation
packages/
├── ui/ # Shared React components
└── configs/ # ESLint/Prettier configurations
documentation/ # Comprehensive guides
docker/ # Production Docker setup
scripts/ # Automation and tooling
Detailed structure: See Monorepo Structure Guide
- Next.js 15: React framework with App Router and React 19
- TypeScript 5.7: Type safety and enhanced developer experience
- Tailwind CSS 4: Utility-first styling with design tokens
- pnpm + Turborepo: Efficient monorepo management and build optimization
- Authentication: NextAuth.js with multiple OAuth providers
- Internationalization: next-intl with 3 languages (EN, PL, HR)
- Theming: Dark/light mode with next-themes
- Components: shadcn/ui with custom design system
- Testing: Jest + React Testing Library + Playwright
- Storybook: Component development and documentation
- ESLint 9 + Prettier: Code quality and formatting
- Husky: Git hooks for quality gates
- Docker: Containerized development and deployment
The application uses Next.js Route Handlers for API endpoints:
- Authentication endpoints:
/api/auth/*(NextAuth.js) - API routes: Located in
apps/frontend/src/app/api/ - Type-safe APIs: Full TypeScript integration with Zod validation
API patterns and development guide: API Development Guide (coming soon)
- Authentication: NextAuth.js (supports Google, GitHub, SAML, credentials)
- Styling: Tailwind CSS with shadcn/ui components
- Icons: Radix UI icons and Lucide React
- Languages: English (default), Polish, Croatian
- Routing: Locale-based URLs (
/en/,/pl/,/hr/) - Management: JSON-based translations with TypeScript declarations
- Server Rendering: Full SSR support with locale detection
Detailed setup: Internationalization Guide
- Standards: WCAG 2.1 AA compliance target
- Components: Built-in a11y with Radix UI primitives
- Testing: Jest-axe integration for automated accessibility testing
- Focus Management: Proper keyboard navigation and focus indicators
- Core Web Vitals: Optimized for LCP, FID, CLS
- Image Optimization: Next.js Image component with responsive loading
- Code Splitting: Automatic route-based and component-based splitting
- Caching: Sophisticated caching strategies for API and static content
NEXTAUTH_SECRET: Authentication secret (auto-generated in dev)NEXTAUTH_URL: Application URL for OAuth callbacks- OAuth providers:
GOOGLE_CLIENT_ID,GITHUB_CLIENT_ID, etc.
.env.local: Local development overrides.env.compose: Docker Compose environment
Complete setup: Environment Variables Guide
# Start new feature with ticket number
git checkout -b feature/PROJ-123-feature-name
# Development with hot reload
pnpm dev
# Quality checks
pnpm pre-commit- Pre-commit hooks: Automatic linting and formatting
- Conventional commits: Standardized commit messages with ticket numbers
- Type checking: Full TypeScript validation across monorepo
# Run all tests
pnpm test
# Component testing
pnpm --filter @infinum/ui test
# E2E testing (when configured)
pnpm --filter frontend test:e2eDetailed workflow: Development Workflow Guide
feature/PROJ-123-description: New features with JIRA/Productive ticket numbersbugfix/PROJ-456-description: Bug fixeshotfix/PROJ-789-description: Critical production fixeschore/PROJ-012-description: Maintenance and tooling
We use a simplified Git Flow focused on rapid iteration and continuous deployment:
- Feature branches from
mainwith descriptive names and ticket numbers - Pull requests with automated quality checks and code review
- Squash merging to maintain clean history
- Automated releases using Changesets for version management
This model works for our team because it maintains code quality while enabling fast iteration and clear traceability to project tickets.
Complete branching guide: Development Workflow Guide
- Create feature branch:
git checkout -b feature/PROJ-123-your-feature - Make changes: Follow existing patterns and conventions
- Quality checks:
pnpm lint && pnpm test - Create PR: Include ticket number and clear description
- Code review: Address feedback and ensure CI passes
- TypeScript: Strict mode enabled, no
anytypes - React: Functional components with hooks
- Styling: Tailwind CSS with design system tokens
- Testing: Unit tests for components, integration tests for features
New UI components should:
- Use CVA for variant management
- Include Storybook stories
- Have comprehensive unit tests
- Follow accessibility best practices
- Include TypeScript declarations
Detailed contribution guidelines: Development Workflow Guide
- Monorepo Structure - Project organization and architecture
- Development Workflow - Git workflow, code review, releases
- UI Components - ShadCN component generation and customization
- Semantic Tokens - Design tokens and theming system
- Internationalization - next-intl setup and configuration
- Environment Variables - Complete environment setup
- Docker Setup - Containerized development and deployment
Technical decisions are documented in Architecture Decision Records following the ADR format for traceability and team alignment.
# Build and run production containers
pnpm docker:prod build
pnpm docker:prod up -d
# Access applications
# Frontend: http://localhost:3000
# Storybook: http://localhost:6006Complete Docker guide: Docker Setup
JS-React-Example is maintained by Infinum.
