Setup & Local Development

Relevant source files

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

• AGENTS.md
• package.json
• pkg/ui/package.json
• pkg/ui/vite.config.ts
• pkg/ui/src/pages/auth/sso/page.tsx
• pkg/convex/projects.ts

This page outlines the architectural requirements, environment configuration, and local development workflows for the Barekey project. Barekey is a developer SaaS vault manager built on a modern stack including Convex, Clerk, and React.

The project is structured as a monorepo using Bun workspaces. The core components consist of a Convex backend (BaaS) and a React Single Page Application (SPA) powered by Vite. Local development relies heavily on the Convex CLI for backend synchronization and Vite for frontend hot-reloading.

Sources: AGENTS.md:7-14, package.json:2-5

Development Environment Setup

Local development requires the installation of the Convex and GitHub CLIs. The environment is configured to share configuration files across the monorepo from the root directory.

Core Dependencies

Category	Tool	Description
Runtime	Bun	Used for package management and workspace orchestration.
Backend	Convex CLI	Syncs schemas, functions, and tails logs.
Frontend	Vite	Provides the development server and build pipeline for the UI.
Auth	Clerk	Handles authentication (Google, GitHub, Passkeys).
Linting	Oxlint / Oxfmt	High-performance linting and formatting tools.

Sources: package.json:7-12, pkg/ui/package.json:11-66, AGENTS.md:14-16

Project Configuration

The Vite configuration for the UI package is set up to resolve environment variables from the monorepo root, ensuring consistency across packages.

export default defineConfig(() => {
  return {
    // Load .env files from the monorepo root
    envDir: path.resolve(__dirname, "../.."),
    resolve: {
      alias: {
        "@": fileURLToPath(new URL("./src", import.meta.url)),
        "@convex": fileURLToPath(new URL("../convex", import.meta.url)),
      },
    },
    // ...
  };
});

Sources: pkg/ui/vite.config.ts:11-20

Local Development Workflow

The development workflow is divided between backend synchronization and frontend execution.

Backend (Convex)

The backend is hosted entirely on Convex. Developers must use the Convex CLI to sync local changes to the cloud-hosted development environment.

The following diagram illustrates the relationship between the local environment and the Convex BaaS:

Frontend (React/Vite)

The frontend is a React SPA that connects directly to Convex via a WebSocket using ConvexReactClient. In local development, the Vite server typically runs on http://localhost:5173.

Sources: AGENTS.md:14-22, AGENTS.md:95-96

Authentication & Identity

Barekey integrates Clerk for authentication and organization management. During local development, a specific "Dev Login" mode can be enabled to bypass standard OAuth flows for faster testing.

Dev Sign-In Flow

When VITE_DEV_LOGIN_ENABLED is set to true in the environment, a developer-specific sign-in action is exposed in the UI.

Critical CLI Commands

The following commands are essential for local development and are executed from the project root.

Command	Description
bun run convex:dev	Starts the Convex development server and syncs local functions.
bun run lint	Runs oxlint across the workspace to check for code quality.
bun run format	Formats all source files using oxfmt.
npx convex logs	Tails live logs from the backend functions.
npx convex data	Allows browsing and inspecting table data in the cloud.

Sources: package.json:7-12, AGENTS.md:275-283

Project Initialization Logic

When a new project is created in an organization, Barekey automatically initializes default stages (environments) via a Convex mutation. This ensures a consistent structure for "Development", "Staging", and "Production".

const DEFAULT_PROJECT_STAGES = [
  { slug: "development", name: "Development" },
  { slug: "staging", name: "Staging" },
  { slug: "production", name: "Production" },
] as const;

// ... Inside createForCurrentOrg mutation
for (const stage of DEFAULT_PROJECT_STAGES) {
  await ctx.db.insert("projectStages", {
    projectId: id,
    orgId: activeOrg.orgId,
    slug: stage.slug,
    name: stage.name,
    isDefault: true,
    // ...
  });
}

Sources: pkg/convex/projects.ts:90-136

Conclusion

Setting up Barekey for local development involves configuring a shared monorepo environment with Bun and syncing the backend via the Convex CLI. By utilizing the built-in Dev Login and automatic stage initialization, developers can quickly pivot from setup to building core vault features and encryption logic.

Sources: AGENTS.md:10-22, pkg/ui/vite.config.ts:1-20