BaseBlocks is a Fair Source, multi-workspace site builder for documentation, knowledge bases, internal portals, onboarding hubs, and public resources.
Teams create structured sites with a block editor, organize pages and document libraries, publish a consistent site experience, and control who can access it.
Documentation: baseblocks.dev/docs
- Block editor — rich text, lists, callouts, code, tables, columns, images, attachments, pages, Mermaid diagrams, and interactive BaseBlocks blocks
- Page trees — nested pages, navigation visibility, page access policies, and embedded page references
- Interactive blocks — quick links, directories, site search, document libraries, and decision trees
- Published sites — responsive sidebar navigation with a transparent content header
- Site identity — optional sidebar logo, site name, and favicon
- Access control — public, private, unlisted, and access-code-protected sites
- Custom domains — DNS verification and managed TLS through Vercel
- Document libraries — uploads, folders, search, text extraction, previews, and downloads
- Integrations — workspace-owned connections with managed OAuth and durable external-content sync
- Workspace management — multiple teams, invitations, roles, and workspace switching
- Internationalization — English and French product UI and documentation
- Self-hosting — Convex backend and S3-compatible file storage
A site can be published or unpublished. Publishing makes the current saved content available at its generated URL and any verified custom domain. Unpublishing removes public access without deleting the site.
Published sites currently read the latest saved page content. Historical deployment snapshots and rollback are not implemented yet.
| Layer | Technology |
|---|---|
| Web | Next.js 16, React 19, Tailwind CSS 4 |
| Editor | OpenEditor, Tiptap, and BaseBlocks extensions |
| Backend | Convex |
| Authentication | Better Auth with email/password and social providers |
| Files | Files SDK with S3-compatible storage |
| UI | shadcn/ui, Radix UI, Base UI, and Hugeicons |
| Monorepo | Turborepo and Bun workspaces |
| Quality | TypeScript, Biome, Bun Test |
- Node.js 20.9 or newer
- Bun 1.3 or newer
- A Convex account
- Access to the linked Vercel project for development environment variables
- An S3-compatible bucket for file uploads
OAuth credentials are only required for the social providers you enable.
git clone https://github.com/BaseBlocks-HQ/BaseBlocks.git
cd BaseBlocks
bun install
bunx vercel link
cp apps/web/.env.example apps/web/.env.local
cp packages/backend/.env.example packages/backend/.env.localEdit each package's environment file for local-only work. In the normal
workflow, bun run dev loads the web runtime from Vercel Development and the
backend runtime from the selected Convex Development deployment. At minimum,
configure Convex, BETTER_AUTH_SECRET, the application URLs, and file storage.
Start the web application and Convex backend:
bun run devThe development command securely loads the linked project's Development variables and a short-lived Vercel OIDC token before starting Turborepo. This lets Editor AI use AI Gateway without storing a Gateway API key locally. The web application runs at http://localhost:3001.
- Development runs on localhost with a personal Convex development deployment.
- Pull requests create Vercel Preview deployments and branch-specific Convex preview deployments.
- Merges to
maindeploy the production Vercel project and production Convex deployment atbaseblocks.dev.
Vercel runs the Convex deployment before the Next.js build using the Build
Command in apps/web/vercel.json. Keep secrets and OAuth clients isolated by
environment; preview deployments use Vercel-generated *.vercel.app URLs.
For local social authentication, configure these provider callbacks:
| Provider | Local callback |
|---|---|
http://localhost:3001/api/auth/callback/google |
|
| GitHub | http://localhost:3001/api/auth/callback/github |
| Microsoft | http://localhost:3001/api/auth/callback/microsoft |
Google also requires http://localhost:3001 as an authorized JavaScript origin.
Production subdomains use Better Auth shared cookies on .baseblocks.dev, configured in packages/backend/convex/auth.ts. Authentication on arbitrary custom domains requires a separate cookie and session design.
Some Microsoft Entra accounts do not include an email claim by default. If a callback returns ?error=email_not_found, add the email optional claim for ID tokens in the Microsoft application registration.
baseblocks/
├── apps/
│ └── web/
│ ├── app/ # Next.js routes and API handlers
│ ├── components/
│ │ ├── file-viewer/ # File previews and upload surfaces
│ │ ├── site-elements/ # Site-specific content primitives
│ │ └── site-runtime/ # Shared editor/viewer runtime contexts
│ ├── features/
│ │ ├── authentication/ # Session and workspace access
│ │ ├── dashboard/ # Sites, members, and workspace shell
│ │ ├── dashboard/integrations/ # Connected apps and lifecycle UI
│ │ ├── editor/ # Editor chrome, sidebar, pages, and settings
│ │ ├── openeditor/ # OpenEditor integration and extensions
│ │ ├── libraries/ # Document-library management
│ │ ├── marketing/ # Website, docs, and legal content
│ │ └── published-sites/ # Public rendering, metadata, and access
│ ├── i18n/ # Next.js locale routing
│ └── lib/ # Auth, Convex, files, routing, and Vercel
├── packages/
│ ├── backend/ # Convex schema, queries, and mutations
│ ├── domain/ # Shared domain models and validators
│ ├── i18n/ # English and French messages
│ └── ui/ # Shared UI components
├── tooling/
│ └── tsconfig/ # Shared TypeScript configuration
├── biome.jsonc # Formatting and architectural boundaries
├── turbo.json # Monorepo task graph
└── package.json # Workspace scripts and dependency policy
bun run dev # Start workspace development processes
bun run build # Build the complete workspace
bun run lint # Lint the repository with Biome
bun run format # Format the repository with Biome
bun run check-types # Run workspace TypeScript checks
bun run test # Run the repository test suite
bun run clean # Remove generated build and task cachesRun a focused test directory with:
bun test apps/web/features/openeditorFile storage is selected through environment variables. The current adapter supports S3-compatible services including AWS S3, Cloudflare R2, MinIO, Backblaze B2, and compatible hosted buckets.
Relevant settings include:
FILES_BUCKETFILES_ENDPOINTFILES_REGIONFILES_FORCE_PATH_STYLEFILES_ACCESS_KEY_IDFILES_SECRET_ACCESS_KEYFILES_MAX_UPLOAD_SIZE_BYTES
Document text extraction can be connected through EXTRACTION_API_URL and EXTRACTION_API_SECRET.
Active areas of work include:
- Continued editor polish and accessibility
- Historical publishing snapshots and rollback
- Broader custom-block APIs
- Templates and starter sites
- Analytics and insights
- Public APIs and embeddable surfaces
- AI-assisted site creation and editing
The roadmap is directional. Repository issues and documentation are the source of truth for shipped behavior.
See CONTRIBUTING.md for local development, code standards, and pull-request guidance.