EncustApp

A SvelteKit application for survey management.

Read the project overview here.

Kanban here.

Requirements

Before starting, make sure you have the following tools installed:

• Node.js Version Manager: You need either fnm or nvm to manage Node.js versions
  • fnm (recommended)
  • nvm
• pnpm: Package manager
  • Install via: npm install -g pnpm
• Turso CLI (required to create and manage the local database)

Project Setup

1. Clone the Repository

git clone [email protected]:rxtsel/encustapp.git
cd encustapp

2. Setup Node.js Version

This project uses a specific Node.js version defined in .node-version.

Using fnm (recommended):

fnm use

Using nvm:

nvm use

If the Node.js version is not installed, install it first:

With fnm:

fnm install
fnm use

With nvm:

nvm install
nvm use

3. Install Dependencies

pnpm install

4. Environment Configuration

Copy the environment example file and configure it with your actual values:

cp .env.example .env

Fill in other required environment variables with your actual configuration values.

5. Database Setup

This project uses SQLite as the database.

The database file will be automatically created in the project root when you run pnpm run dev command.

First time setup:

# Option 1: Push schema directly (recommended for development)
pnpm run db:push

# Option 2: Generate and run migrations
pnpm run db:generate
pnpm run db:migrate

6. Start Development Server

pnpm run dev

The application will be available at http://localhost:5173 (or the port shown in your terminal).

Development Workflow

Git Flow

This project uses Git Flow methodology with the following branches:

• main: Production-ready code
• develop: Integration branch for features
• feature/: Feature branches (e.g., feature/user-authentication)

Branch Workflow

1. Create feature branches from develop:

   git checkout develop
   git pull origin develop
   git checkout -b feature/your-feature-name

2. Work on your feature and commit changes

3. Push your feature branch:

   git push origin feature/your-feature-name

4. Create a Pull Request to merge into develop

5. After review and approval, the feature will be merged

Conventional Commits

This project uses Conventional Commits specification. We have tools to help enforce this:

Making Commits

This project enforces Conventional Commits specification. You have two options for making commits:

Option 1 - Using Commitizen (Recommended):

git add .
pnpm run commit

This will launch commitizen which will guide you through:

1. Selecting the type of change (feat, fix, docs, etc.)
2. Adding a scope (optional)
3. Writing a short description
4. Adding a longer description (optional)
5. Noting any breaking changes (optional)

Option 2 - Manual commits:

git add .
git commit -m "feat: add user authentication"

Manual commits must follow the conventional format or they will be rejected by commit hooks.

Using Git UI tools (lazygit, GitKraken, etc.):

If you use GUI tools like lazygit, write your commit messages manually following the conventional format. The commit-msg hook will validate the format automatically.

Commit Message Format

If not using git cz, follow this format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types:

• feat: A new feature
• fix: A bug fix
• docs: Documentation only changes
• style: Changes that do not affect the meaning of the code
• refactor: A code change that neither fixes a bug nor adds a feature
• perf: A code change that improves performance
• test: Adding missing tests or correcting existing tests
• chore: Changes to the build process or auxiliary tools

Examples:

feat: add user authentication
fix: resolve login validation issue
docs: update README with setup instructions
chore: update dependencies

Automated Quality Checks

The project uses lefthook to automatically run quality checks:

Pre-commit hooks:

• Linting with ESLint
• Code formatting with Prettier
• Type checking with TypeScript

Commit message hooks:

• Commit message validation with commitlint (ensures conventional format)

Pre-push hooks:

• Final type checking
• Final linting

These hooks are automatically installed when you run pnpm install thanks to the prepare script.

Available Scripts

• pnpm run dev - Start development server
• pnpm run check - Run type checking
• pnpm run format - Format code with Prettier
• pnpm run lint - Lint code with ESLint
• pnpm run commit - Create a commit using Commitizen
• pnpm run db:push - Push database schema
• pnpm run db:generate - Generate database migrations
• pnpm run db:migrate - Run database migrations
• pnpm run db:studio - Open database studio
• pnpm run db:seed - Populate database with test data
• pnpm run db:reset - Reset database (clear all data)

Additional Resources

• SvelteKit Documentation
• Git Flow Workflow
• Conventional Commits
• Commitizen
• Lefthook
• Turso Documentation