u11d-com/stytch-nestjs-starter
A production-ready NestJS backend starter with Stytch authentication integration
A production-ready NestJS backend starter with Stytch authentication integration
This starter template provides a robust, production-ready NestJS backend with Stytch authentication integration. Instead of building authentication from scratch (which is complex and risky), this template leverages Stytch's secure, battle-tested authentication platform.
sequenceDiagram
participant C as Client
participant API as NestJS API
participant R as Redis
participant S as Stytch
participant DB as PostgreSQL
C->>API: POST /auth/login
API->>S: Authenticate user
S-->>API: Session token + user data
API->>DB: Get/create user record
API->>R: Cache session with TTL
API-->>C: Return session token
Note over C,DB: Subsequent requests
C->>API: GET /resources (Bearer token)
API->>R: Check cached session
R-->>API: Return user session
API-->>C: Return protected data
Note over C,DB: Session refresh
API->>S: Extend session (if threshold met)
S-->>API: New session token
API->>R: Update cache
API-->>C: New token in X-New-Session-Token header
No download data available
No tracked packages depend on this.
graph TB
C[Client Application] --> API[NestJS API Server]
API --> R[Redis Cache]
API --> DB[PostgreSQL Database]
API --> S[Stytch Service]
git clone https://github.com/u11d-com/stytch-nestjs-react-starter.git
cd stytch-nestjs-react-starter
yarn install
cp .env.example .env
Configure your .env file which will be used for local development.
# Start PostgreSQL and Redis
docker compose up postgres redis -d
# Run database migrations
yarn migration:run
yarn start:dev
Your API will be available at http://localhost:3000
| Script | Description |
|---|---|
yarn start:dev | Start development server with hot reload |
yarn build | Build the application |
yarn start:prod | Start production server |
yarn migration:generate | Generate new database migration |
yarn migration:run | Run pending migrations |
yarn create-user <email> | Create admin user (sends magic link) |
yarn test | Run unit tests |
yarn test:e2e | Run end-to-end tests |
yarn lint | Lint and fix code |
| Method | Endpoint | Description |
|---|---|---|
POST | /auth/sign-up | Create new user account |
POST | /auth/login | Authenticate user |
POST | /auth/password | Set password using magic link token |
| Method | Endpoint | Description | Auth |
|---|---|---|---|
POST | /auth/refresh | Refresh session token | Bearer |
POST | /auth/logout | Revoke session | Bearer |
GET | /resources | Access protected resources | Bearer |
| Method | Endpoint | Description | Auth |
|---|---|---|---|
POST | /auth/invite | Create user and send magic link | Master Key |
Users can create their own accounts:
curl -X POST http://localhost:3000/auth/sign-up \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "SecurePassword123!",
"firstName": "John",
"lastName": "Doe"
}'
Admins can invite users (sends magic link email) using master key:
# One can use predefined script
yarn create-user admin@company.com
# ...or execute the endpoint manually
curl -X POST http://localhost:3000/auth/invite \
-H "Content-Type: application/json" \
-H "X-Api-Key: your-master-key" \
-d '{
"email": "newuser@company.com",
"firstName": "Jane",
"lastName": "Smith"
}'
The system automatically refreshes sessions when they're close to expiring:
STYTCH_SESSION_REFRESH_THRESHOLD_MINUTES (default: 30)X-New-Session-Token headercurl -X GET http://localhost:3000/resources \
-H "Authorization: Bearer your-session-token"
# Copy and configure Docker environment
cp .env.example .env.docker
# Start all services
docker compose up -d
# Check logs
docker compose logs -f server
Control how long sessions last:
STYTCH_SESSION_DURATION_MINUTES=60 # Sessions expire after 1 hour
Control when sessions are automatically refreshed:
STYTCH_SESSION_REFRESH_THRESHOLD_MINUTES=30 # Refresh when <30min left
To use a different cache provider, update the CacheModule configuration in app.module.ts:
CacheModule.register({
// Your cache configuration
});
Potential extensions (let us know if you're interested!):
Stytch Configuration Errors
STYTCH_PROJECT_ID and STYTCH_SECRET are correctDatabase Connection Issues
docker compose up postgres -dyarn migration:runRedis Connection Issues
docker compose up redis -dREDIS_URL configurationSession Issues
Bearer <token>git checkout -b feature/my-featuregit commit -am 'Add some feature'git push origin feature/my-featureThis project is licensed under the MIT License - see the LICENSE file for details.
Made with โค๏ธ by u11d