Skip to main content
This guide walks you through setting up CodeInk for local development. The entire setup process takes less than 5 minutes.

​
Prerequisites

Before you begin, ensure you have the following installed:

Bun

CodeInk uses Bun as its JavaScript runtime and package managerInstall Bun

Node.js 18+

Optional but recommended for compatibilityInstall Node.js

​
Quick Start

1

Clone the repository

Clone the CodeInk repository from GitHub:
git clone https://github.com/jorgefl8/codeink.git
cd codeink
2

Install dependencies

Install all required dependencies using Bun:
bun install
This will install all packages defined in package.json, including:
  • Astro framework and integrations
  • CodeMirror editor and extensions
  • Markdown processing libraries (marked, remark)
  • Syntax highlighting (Shiki)
  • Math rendering (KaTeX) and diagrams (Mermaid)
3

Start the development server

Launch the development server:
bun dev
The development server will start at:
http://localhost:4321
The server supports hot module replacement (HMR), so changes to your code will be reflected immediately in the browser.
4

Open in browser

Navigate to http://localhost:4321 in your web browser to see CodeInk running locally.

​
Available Scripts

CodeInk provides several npm scripts for development and production: 
bun dev
# Starts the Astro development server on port 4321
# Includes hot module replacement

​
Project Structure

After cloning, your project directory will look like this: 
codeink/
├── src/
│   ├── components/     # Astro components
│   ├── layouts/        # Page layouts
│   ├── pages/          # Route pages
│   ├── scripts/        # Client-side TypeScript
│   ├── lib/            # Utility libraries
│   ├── styles/         # CSS files
│   └── assets/         # Static assets (SVGs, icons)
├── public/             # Static files served as-is
├── astro.config.mjs    # Astro configuration
├── package.json        # Dependencies and scripts
├── tsconfig.json       # TypeScript configuration
└── wrangler.toml       # Cloudflare deployment config
See Code Structure for a detailed breakdown of each directory.

​
Development Workflow

​
Making Changes

  1. Edit components in src/components/ or src/pages/
  2. Modify styles in src/styles/
  3. Update scripts in src/scripts/
Changes are automatically detected and the browser refreshes.

​
Type Checking

Run type checking before committing: 
bun run lint
Always fix TypeScript errors before submitting pull requests.

​
Building for Production

Create an optimized production build: 
bun run build
The build process:
  1. Type checks all TypeScript files
  2. Bundles JavaScript with Vite
  3. Optimizes assets (images, CSS, fonts)
  4. Code splits vendor libraries:
    • vendor-codemirror: CodeMirror editor
    • vendor-marked: Markdown parser
    • vendor-remark: Markdown linter
  5. Generates server-side rendered pages
Output is placed in the dist/ directory.

​
Preview Production Build

Test the production build locally: 
bun run preview

​
Environment Configuration

CodeInk runs entirely client-side with no environment variables required for development.

​
Deployment Configuration

For production deployment to Cloudflare Pages, the following configuration is used:
wrangler.toml
name = "codeink"
compatibility_date = "2024-01-01"
pages_build_output_dir = "dist"

​
Troubleshooting

If port 4321 is taken, Astro will automatically try the next available port. You can also specify a custom port:
bun dev --port 3000
Try clearing Bun’s cache and reinstalling:
rm -rf node_modules bun.lock
bun install
Ensure your editor is using the workspace TypeScript version:VS Code: Press Cmd+Shift+P and select “TypeScript: Select TypeScript Version” → “Use Workspace Version”
  1. Hard refresh the browser (Cmd+Shift+R or Ctrl+Shift+R)
  2. Restart the development server
  3. Clear browser cache and IndexedDB

​
Next Steps

Architecture

Learn about CodeInk’s technical architecture

Code Structure

Explore the codebase organization

Contributing

Start contributing to CodeInk

Build docs developers (and LLMs) love

Get started for freeTalk to us