Developer Environment Setup

Relevant source files

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

• WARP.md
• README.md
• test-setup.js
• client/static/build.js
• deployment/README.md
• client/landing/routes/+page.server.ts
• client/landing/routes/pricing/+page.server.ts
• client/landing/shared/faqs.data.ts
• client/cx/contemporaries/notion.json
• client/cx/contemporaries/obsidian.json

The Nucleus repository is an open-source library that powers a suite of personal productivity and well-being tools. The project is structured as a monorepo, utilizing Turbo for build orchestration. The frontend is built with SvelteKit and TailwindCSS, while the backend uses Node.js. This setup allows for shared code across multiple products and streamlined development workflows.

The primary products built from this repository are Nucleus (a super app), Memotron (a knowledge management tool), and Pointron (a focus and time management tool). All are intended for personal use.

Sources: WARP.md:5-12, README.md:5-19

Project Architecture

The repository uses a monorepo architecture to manage code for multiple products and shared libraries. This structure is orchestrated by Turbo.

Sources: WARP.md:14-16

Monorepo Structure

The directory structure is organized to separate shared packages from product-specific implementations.

This diagram illustrates the high-level directory structure of the monorepo.
Sources: WARP.md:17-29

Key directories include:

• client/: Contains frontend code, with subdirectories for individual product apps (client/products/) and shared UI elements.
• packages/: Houses shared libraries used across different parts of the monorepo.
• server/: Contains backend API and database logic.
• shared/: For code shared between the client and server, such as types and utils.
• deployment/: Holds deployment configurations.
• tests/: Contains test files for the project.

Sources: WARP.md:17-29

Core Products

The repository is used to build several distinct productivity applications.

Name	Website	Description
Nucleus	nucleus.to	A super app that combines all other tools.
Memotron	memotron.app	A tool for managing knowledge (PKM, note-taking).
Pointron	pointron.app	A tool for tracking goals and managing time.

Sources: README.md:12-19, WARP.md:7-11

Development Workflow

The development process is managed through a series of npm scripts, which leverage Turbo to execute tasks across the workspace.

Sources: WARP.md:34-35

Common Commands

The following commands are used for common development, building, and testing tasks.

Command	Description
npm run dev	Starts all applications in development mode.
npm run dev:nucleus	Starts only the Nucleus app.
npm run dev:memotron	Starts only the Memotron app.
npm run dev:pointron	Starts only the Pointron app.
npm run build	Builds all packages and applications.
npm run build:packages	Builds only the shared packages.
npm run build:products	Builds only the product applications.
npm run test	Runs all tests.
npm run lint	Runs the linter.
npm run clean	Cleans build artifacts.
node test-setup.js	Runs a script to verify the workspace setup.

Sources: WARP.md:39-61

Single Product Development

When focusing on a single product, developers can navigate to its specific directory (e.g., client/products/nucleus) and run commands directly. These product-specific scripts allow for building and running the app for different environments (pre, live).

Sources: WARP.md:64-83

Workspace Verification

A utility script is provided to ensure the developer's workspace is correctly configured. This script can be run using node test-setup.js.

Sources: test-setup.js:3

The verification process performs the following checks:

1. Package Validation: Verifies that all expected shared libraries exist in the packages/ directory.
2. Product App Validation: Checks for the existence of each product application directory within client/products/ and confirms that each contains a package.json file.
3. Turbo Configuration: Ensures that the root turbo.json and package.json files are present.

This flowchart shows the logic of the test-setup.js script for verifying the workspace.
Sources: test-setup.js:19-74

Static Asset Handling

The static package has a dedicated build script to manage assets like images and fonts.

Sources: client/static/build.js:6

The build process involves two main steps:

1. Manifest Creation: The createAssetManifest function scans the directory for assets and generates an assets-manifest.json file. This manifest lists all available assets, their versions, and a timestamp.
2. Asset Copying: The copyAssetsTo function provides a mechanism to copy all static assets to a specified target directory, which is useful for consuming applications.

This sequence diagram outlines the process of building the static package and copying assets.
Sources: client/static/build.js:10-46

Self-Hosting

The project supports self-hosting for the frontend applications. This allows a user to deploy an offline-only version of an app to their own server.

Sources: README.md:22-24, client/landing/shared/faqs.data.ts:40-42

To deploy a self-hosted frontend, follow these steps:

1. Clone or fork the repository.
2. Choose the desired application from the client/products/ directory.
3. Set the required environment variables.
4. Deploy to a hosting provider.

Environment Variables

The following environment variables must be set for a self-hosted deployment:

Variable	Description	Example Value
VITE_PRODUCT	Specifies which product to build.	memotron, pointron, or nucleus
VITE_STATIC_URL	The base URL for static assets.	https://cdn.21n.co

Sources: README.md:28-31

Full-stack deployment, including the backend on Cloudflare (Workers, D1, R2), is planned for the future.

Sources: README.md:34