Skip to main content

​
Prerequisites

Before getting started with Skiff development, ensure you have the following installed:
  • Node.js: Version 20.9.0 or higher
  • Yarn: Version 4.0.1 (managed via Corepack)
  • Git: For version control

​
Initial Setup

Follow these steps to set up your local development environment:
1

Clone the Repository

Fork and clone the Skiff repository to your local machine:
git clone https://github.com/<your-username>/skiff-apps.git
cd skiff-apps/
Add the upstream remote to keep your fork synchronized:
git remote add upstream https://github.com/skiff-org/skiff-apps.git
2

Set Yarn Version

The project uses Yarn Berry (v4.0.1). Set the correct version:
yarn set version berry
This ensures you’re using the Yarn version specified in the project’s packageManager field.
3

Install Dependencies

Install all workspace dependencies:
yarn install
This will install dependencies for all workspaces in the monorepo, including:
  • Root dependencies
  • Library packages in libs/
  • Application packages (skemail-web, calendar-web, etc.)
4

Build Libraries

Before running any application, build the shared libraries:
yarn build:lib
This command builds the libraries in the following order:
  1. skiff-utils
  2. skiff-mail-protos
  3. skiff-graphql
  4. @skiff-org/skiff-crypto
  5. skiff-front-graphql
  6. skiff-front-utils
Libraries must be built in topological order due to their dependencies on each other.
5

Run the Development Server

Start the default development server (Skiff Mail):
yarn dev
This runs skemail-web in development mode. Navigate to:
http://localhost:4200/mail/inbox
The development build currently uses mock data. Live API access may be added in future updates.

​
Running Individual Applications

The monorepo contains multiple applications. Here’s how to run each one:

​
Skiff Mail (skemail-web)

yarn workspace skemail-web dev
Access at: http://localhost:4200/mail/inbox

​
Skiff Calendar (calendar-web)

yarn workspace calendar-web dev
Access at: http://localhost:4200/calendar

​
Development Scripts

​
Root-Level Scripts

ScriptDescription
yarn build:libBuild all libraries in libs/
yarn devRun skemail-web in development mode

​
Application-Level Scripts

Each application (skemail-web, calendar-web) has its own set of scripts:
ScriptDescription
yarn devStart development server
yarn buildProduction build
yarn testRun tests
yarn lintCheck code style with ESLint
yarn lint:fixAuto-fix linting issues
yarn tsType-check without emitting files

​
Common Development Tasks

​
Syncing Your Fork

Keep your local main branch up to date: 
git checkout main
git pull upstream main

​
Creating a Feature Branch

git checkout -b feature-branch-name

​
Cleaning Build Artifacts

If you encounter build issues, clean the build artifacts: 
# Clean skemail-web build
yarn workspace skemail-web build:clean

# Clean Yarn cache
yarn workspace skemail-web webpack:clean

​
Environment Configuration

Some applications use environment variables for configuration:
  • skemail-web: Uses dotenv for environment configuration
  • calendar-web: Uses dotenv with different configs for dev/production
Check each application’s configuration files for available environment variables.

​
Troubleshooting

Ensure you’ve built the libraries first:
yarn build:lib
Libraries must be built before applications can use them.
The project requires Yarn 4.0.1. Reset the version:
yarn set version berry
Check the version:
yarn --version
If port 4200 is already in use, you can:
  • Stop the process using the port
  • Modify the webpack dev server configuration to use a different port

​
Next Steps

Monorepo Structure

Learn about the workspace organization

Contributing

Read the contribution guidelines

Testing

Understand the testing setup

Build docs developers (and LLMs) love

Get started for freeTalk to us