teableio_teable/CONTRIBUTING.md

Contributing

The base branch is develop.

Development Setup

Note

The following commands are for Linux/Mac environments. For Windows, please use WSL2.

1. Initial Setup

# Enable the Package Manager
corepack enable

# Install project dependencies
pnpm install

2. Database Selection

We support SQLite (dev only) and PostgreSQL. PostgreSQL is recommended and requires Docker installed.

# Switch between SQLite and PostgreSQL
make switch-db-mode

3. Environment Configuration (Optional)

cd apps/nextjs-app
cp .env.development .env.development.local

4. Start Development Server

cd apps/nestjs-backend
pnpm dev

This will automatically start both backend and frontend servers with hot reload enabled.

Continuous Development

After pulling the latest code, ensure your development environment stays up-to-date:

# Update dependencies to latest versions
pnpm install

# Update database schema to latest version
make switch-db-mode

Known Issues

Port conflict: In dev mode, code changes trigger hot reloading. If changes affect app/nestjs-backend (packages/core, packages/db-main-prisma), nodejs may restart, potentially causing port conflicts. If backend code changes seem ineffective, check if the port is occupied with lsof -i:3000. If so, kill the old process with kill -9 [pid] and restart the application with pnpm dev.

Websocket: In development, Next.js occupies port 3000 for websocket to trigger hot reloading. To avoid conflicts, the application's websocket uses port 3001. That's why you see SOCKET_PORT=3001 in .env.development.local, while in production, port 3000 is used by default for websocket requests.

Database Migration Workflow

Teable uses Prisma as ORM for database management. Follow these steps for schema changes:

1. Modify packages/db-main-prisma/prisma/template.prisma

2. Generate Prisma schemas:

make gen-prisma-schema

This generates both SQLite and PostgreSQL schemas and TypeScript definitions.

3. Create migrations file:

make db-migration

4. Apply migrations:

make switch-db-mode

Note

If you need to modify the schema after applying migrations, you need to delete the latest migration file and run pnpm prisma-migrate-reset in packages/db-main-prisma to reset the database. (Make sure you run it in the development database.)

Testing

E2E Tests

Located in apps/nestjs-backend:

# First-time setup
pnpm pre-test-e2e

# Run all E2E tests
pnpm test-e2e

# Run specific test file
pnpm test-e2e [test-file]

Unit Tests

# Run all unit tests
pnpm g:test-unit

# Run tests in specific package
cd packages/[package-name]
pnpm test-unit

# Run specific test file
pnpm test-unit [test-file]

IDE Integration

Using VSCode/Cursor:

1. For E2E tests in apps/nestjs-backend:

   • Switch to test file (e.g. apps/nestjs-backend/test/record.e2e-spec.ts)
   • Select "vitest e2e nest backend" in Debug panel

2. For unit tests in different packages:

   • For packages/core:
     • Switch to test file (e.g. packages/core/src/utils/date.spec.ts)
     • Select "vitest core" in Debug panel
   • For other packages, select their corresponding debug configuration

Each package has its own debug configuration in VSCode/Cursor, make sure to select the matching one for the package you're testing.

Git Commit Convention

This repo follows conventional commit format.

Common Prefixes

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• test: Adding or modifying tests
• refactor: Code changes that neither fix bugs nor add features
• style: Changes to styling/CSS
• chore: Changes to build process or tools

Note

Full configuration can be found in commitlint.config.js

Docker Build

Building Images Locally

• teable: The main application image

Build the Application Image

Note

You should run this command in the root directory.

# Build the main application image
docker build -f dockers/teable/Dockerfile -t teable:latest .

# Build for a specific platform (e.g., amd64)
docker build --platform linux/amd64 -f dockers/teable/Dockerfile -t teable:latest .

Pushing to Docker Hub

# Tag your local image
docker tag teable:latest your-username/teable:latest

# Login to Docker Hub
docker login

# Push the image
docker push your-username/teable:latest