dashore-incubator/START-HERE.md

Start Here

get up and running with dashore incubator development in 5 minutes.

prerequisites

required:

• bun 1.0+ - bun.sh (curl -fsSL https://bun.sh/install | bash)
• node.js 18+ - nodejs.org (bun handles most things, but some tools need node)
• git - for version control

optional:

• wrangler cli - for cloudflare deployment (bun add -g wrangler)

quick start

1. clone and setup

---

# clone the repository (or your fork)
git clone https://github.com/dashore-incubator/dashore-incubator.git
cd dashore-incubator

# install dependencies
bun install

2. configure environment

---

# copy the example env file
cp .env.example .env.local

# edit .env.local with your values:
# - WORKOS_CLIENT_ID (from WorkOS dashboard)
# - WORKOS_API_KEY (from WorkOS dashboard)
# - WORKOS_COOKIE_PASSWORD (32+ random characters)

if you don't have WorkOS credentials, you can still run the app - you just won't be able to authenticate.

3. start development

---

# start the dev server with turbopack
bun dev

4. open in browser

---

navigate to http://localhost:3000 - you should see the login page!

project structure

dashore-incubator/
├── src/
│   ├── app/                 # Next.js App Router
│   │   ├── api/             # API routes (auth callbacks)
│   │   ├── dashboard/       # Dashboard pages
│   │   ├── actions/         # Server actions
│   │   └── page.tsx         # Login page
│   ├── components/          # React components
│   │   ├── ui/              # shadcn/ui base components
│   │   └── ...              # App-specific components
│   ├── hooks/               # Custom React hooks
│   ├── lib/                 # Utilities and helpers
│   └── middleware.ts        # Auth middleware
├── Documentation/           # Contributor docs
├── .github/                 # GitHub workflows
├── CLAUDE.md                # AI assistant context
└── wrangler.jsonc           # Cloudflare config

key commands

# development
bun dev              # start dev server with turbopack (port 3000)
bun run lint         # run eslint

# cloudflare
bun run preview      # build and preview on cloudflare runtime
bun run deploy       # build and deploy to production

troubleshooting

"module not found" errors

# clear node_modules and reinstall
rm -rf node_modules .next
bun install

turbopack issues

# try without turbopack
bun run dev --no-turbo

auth not working

• check your .env.local has all required vars
• ensure WORKOS_COOKIE_PASSWORD is 32+ characters
• check the browser console for errors

build fails on cloudflare preview

# make sure opennext is building correctly
bun run build
# then try preview again
bun run preview

key files

Purpose	File
Main page (login)	src/app/page.tsx
Dashboard	src/app/dashboard/page.tsx
Auth middleware	src/middleware.ts
Auth callback	src/app/api/auth/[...authkit]/route.ts
Sign out action	src/app/actions/auth.ts
Sidebar component	src/components/app-sidebar.tsx
UI components	src/components/ui/

development workflow

branch strategy

never push to main. always work on feature branches:

git checkout -b <username>/<feature-name>

# example
git checkout -b nicholai/add-settings-page

making changes

1. create a feature branch
2. make your changes
3. run bun run lint to check for issues
4. test with bun run preview (cloudflare runtime)
5. commit with conventional commits
6. open a PR

next steps

1. explore the codebase - start with src/app/page.tsx
2. read CLAUDE.md - understand the project context and conventions
3. check issues - find something to work on
4. join discord - ask questions, get help

welcome to the team!