Local Development Setup

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• package.json
• pages/api/dispatch.ts
• jest.config.ts
• prettier.config.js
• public/mails/email.html
• pages/_app.tsx

This document provides a comprehensive guide to setting up the Heyme application for local development. Heyme is a Next.js application that allows users to send video messages to their future selves, which are delivered via email on a scheduled date. This guide covers prerequisites, environment configuration, application dependencies, and running the development server.

The application is built with a modern web stack, integrating several key services for its functionality. The architecture relies on a MySQL database for data storage, Zeptomail for sending transactional emails, and browser-native Web Media APIs for recording video messages.

Sources: README.md

1. System Architecture

The application's architecture is composed of a Next.js frontend and backend, which interacts with a MySQL database for persistence and the Zeptomail service for email delivery.

This diagram illustrates the high-level architecture of the Heyme application.

2. Prerequisites

Before starting the setup process, ensure your development environment meets the following requirements.

Tool	Version/Requirement	Installation
Node.js	16.4.0	Required for the runtime environment.
yarn	Classic	The specified package manager.

Sources: README.md:31-33

3. Installation and Setup

Follow these steps to get the development environment running. The process involves cloning the repository, setting up environment variables, and starting the server.

This flowchart outlines the setup process from cloning the repository to running the application.

3.1. Clone the Repository

First, clone your fork of the repository to your local machine.

git clone <your fork>

Sources: README.md:36-38

3.2. Environment Configuration

The application requires specific environment variables for connecting to external services. Copy the example file to create your local configuration.

cp .env.example .env.local

You must then update .env.local with your specific credentials for the following services:

Variable	Description	Source File
ZEPTOMAIL_TOKEN	API token for the Zeptomail service to send emails.	pages/api/dispatch.ts:51
SITE_URL	The base URL of the application, used in email links.	pages/api/dispatch.ts:80
Database Credentials	Credentials for the MySQL connection (host, user, password, etc.).	pages/api/dispatch.ts:44

Sources: README.md:39-41, pages/api/dispatch.ts:44-80

4. Key Dependencies

The project relies on several key libraries and frameworks. The full list is available in package.json.

Dependency	Version	Description
next	^13.1.6	The React framework for the application.
react	^18.2.0	The JavaScript library for building the user interface.
knex	^2.4.2	SQL query builder for interacting with the MySQL database.
mysql	^2.18.1	The MySQL database driver.
zeptomail	^3.0.3	Client library for the Zeptomail transactional email service.
jest	^29.5.0	The testing framework used for unit and integration tests.
next-themes	^0.2.1	Enables dark mode functionality.
@highlight-run/next	^2.2.2	Used for application monitoring and error tracking.

Sources: package.json:11-73, pages/_app.tsx:16

5. Available Scripts

The package.json file defines scripts for common development tasks like running, building, and testing the application.

Script	Command	Description
dev	next dev	Starts the Next.js development server.
build	next build	Builds the application for production.
start	next start	Starts a production server.
lint	next lint	Runs the ESLint linter to check for code quality issues.
test	jest	Executes the test suite using Jest.
test:debug	node --inspect-brk ...	Runs Jest in debug mode.

Sources: package.json:5-11

5.1. Running the Development Server

To start the application in development mode with hot-reloading, run:

yarn dev

Sources: README.md:42-44

6. Testing

The project uses Jest for testing. The configuration is defined in jest.config.ts, which sets up the test environment (jest-environment-jsdom), transformers (babel-jest), and module path aliases for easier imports in test files.

// jest.config.ts
const config: Config.InitialOptions = {
  testEnvironment: 'jest-environment-jsdom',
  transform: {
    "^.+\\.(ts|js)x?$": "babel-jest",
  },
  // ...
  moduleNameMapper: {
    "^@/pages(.*)$": "<rootDir>/pages/$1",
    "^@/components(.*)$": "<rootDir>/components/$1",
    // ...
  },
};

Tests are located in the tests/ directory and cover API endpoints and frontend components. For example, tests/api/dispatch.spec.ts tests the email content generation logic.

Sources: jest.config.ts, tests/api/dispatch.spec.ts

7. Code Style and Formatting

Code formatting is enforced by Prettier. The configuration in prettier.config.js specifies rules for line endings, quotes, and import order. This ensures a consistent code style across the entire project.

// prettier.config.js
module.exports = {
  endOfLine: "lf",
  semi: false,
  singleQuote: false,
  tabWidth: 2,
  trailingComma: "es5",
  importOrder: [
    // ... import order rules
  ],
  // ...
}

Sources: prettier.config.js