This repository is a collection of modern web development tools aimed at creating fast, robust, and future-proof applications. These applications are designed to handle complex business domains, utilizing a domain-driven approach and setup to ensure scalability and maintainability. This repository is about:
- Using minimal and well-known libraries
- Writing clean code is a domain driven approach
- Well tested with unit tests and e2e tests
To get started, you need pnpm and docker.
git clone https://github.com/mathi123/neurotic-web.git
cd neurotic-web
cp .env.example .env
pnpm i
pnpm db:start
pnpm db:migrateCheck the env file and to start the dev server run:
pnpm devNext.js was installed using manual install procedure. This contains a section on TypeScript setup in VS Code.
The tsconfig file contains settings for compiling TypeScript. The following settings were modified:
- allowJs: set to false
- strict: set to true
In order for @/... imports to work, the following config was added:
"baseUrl": ".",
"paths": {
"@/*": ["app/*"]
}Commit messages must use the Conventional Commits config.
ESLint was set up to use 3 rule sets:
- Next.js rules
- TypeScript rules
- Prettier rules (such that they don't conflict)
The max-len rule is disabled for files in app/app/components/ui to allow longer lines in UI component files generated by ShadCN.
Prettier is used to automatically format code. The .prettierrc configures prettier and has a module to automatically format tailwind css. The settings.json file has a small section (files.associations) that associates css files with this plugin, such that syntax highlighting works correctly.
The Node.js version is indicated in .npmrc, and the pnpm version in package.json. These versions are also used on CI/CD. Be careful to run commands with pnpm, not your local npm version.
Vitest is used for running unit tests.
pnpm test
# Or with code coverage
pnpm test:coverage
Prisma is used as an ORM. Modify the schema.prisma file, and add a migration as follows:
pnpm db:migrateNotes:
- Neon Adapter is used on production and Pg Adapter for local development
- To check: connection pooling still relevant with Neon driver?
Better-auth is used for authentication. It supports email/password authentication and GitHub OAuth. Another open source package better-auth-ui is used, to serve default pages for login, sign-up, password reset etc. In case this package is not maintained anymore, the views from it can just be copied over.
The auth server is configured in app/auth.ts:
- Database: Uses Prisma adapter with PostgreSQL
- Email/Password: Enabled by default
- Social Providers: GitHub OAuth (requires
GITHUB_CLIENT_IDandGITHUB_CLIENT_SECRET)
Auth API routes are handled at /api/auth/[...all] via the Next.js route handler in app/api/auth/[...all]/route.ts.
The auth client for React components is available via app/app/auth.ts:
import { authClient } from '@/app/auth';
// Use authClient methods in your componentsThe authentication system uses the following Prisma models:
User: User accountsSession: Active user sessionsAccount: OAuth provider accountsVerification: Email verification tokens
These models are automatically created when running the auth migration.
Copy .env.example to .env and fill in your values. The app loads .env locally; .env is gitignored and not used in CI/CD.
| Variable | Description |
|---|---|
| DATABASE_URL | The database url. |
| DATABASE_URL_UNPOOLED | Direct database url, without connection pooling. |
| GITHUB_CLIENT_ID | GitHub OAuth client ID (required for GitHub auth). |
| GITHUB_CLIENT_SECRET | GitHub OAuth client secret (required for GitHub auth). |
Tailwind was installed using the manual instructions with postcss. You can use the Tailwind CSS IntelliSense plugin for VSCode.
ShadCn is used to build a compent library in this codebase. The manual instructions were also followed to install this. The theming is configured to use a dark mode.
All external URLs referenced in the README.md are automatically validated in CI/CD. The validation ensures that all links are accessible and will fail the CI/CD pipeline if any URLs are broken or inaccessible.
To validate URLs locally:
pnpm run docsThis log explains why packages were installed.
| Reason | Package(s) |
|---|---|
| Next.js setup | next@latest, react@latest, react-dom@latest |
| commit message linting | @commitlint/config-conventional, @commitlint/cli, husky |
| ESLint via Next.js | eslint, eslint-config-next, eslint-config-prettier, @eslint/eslintrc |
| validating models | zod |
| prisma ORM setup | prisma, @prisma/client, @prisma/adapter-neon, @prisma/adapter-pg |
| Unit testing setup | vitest, vite-tsconfig-paths, jsdom, @vitejs/plugin-react, @testing-library/dom, @testing-library/react |
| Unit test coverage | @vitest/coverage-v8 |
| Tailwind setup | tailwindcss, @tailwindcss/postcss, postcss, prettier-plugin-tailwindcss |
| ShadCn setup | class-variance-authority, clsx, tailwind-merge, lucide-react, tw-animate-css |
| Button Component | @radix-ui/react-slot |
| Dropdown Menu Component | @radix-ui/react-dropdown-menu |
| Dark mode | next-themes |
| Label Component | @radix-ui/react-label |
| Separator Component | @radix-ui/react-separator |
| Auth setup | better-auth |
| Auth UI Setup | @daveyplate/better-auth-ui |
| Toastr Component | sonner |
| ShadCN Table/Select | radix-ui |
| Data Table | @tanstack/react-table |
| Sidebar Component | (shadcn generated - uses radix-ui) |
| Navigation Menu/Avatar | (shadcn generated - uses radix-ui) |
| Faceted Filter | cmdk (shadcn command component) |
| Internationalization | next-intl |
TurboPack and @prisma/pg-adapter don't work well together, for pnpm. The following error is thrown when instantiating the adapter.
Package pg can't be external
The request pg matches serverExternalPackages (or the default list).
The request could not be resolved by Node.js from the project directory.
Packages that should be external need to be installed in the project directory, so they can be resolved from the output files.
Try to install it into the project directory by running npm install pg from the project directory.A temporary fix was to modify the .npmrc file as mentioned here.
public-hoist-pattern[]=*pg*