mirror of
https://github.com/NicholaiVogel/dashore-incubator.git
synced 2026-03-30 22:38:56 +00:00
Nicholai
2e051e4bef
- add WorkOS AuthKit authentication with middleware protection - add dashboard with sidebar layout (shadcn/ui components) - add contributor documentation (CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, START-HERE, Documentation/) - add CI workflow for lint and build on PRs - switch from pnpm to bun - add CLAUDE.md and AGENTS.md for AI assistant context
182 lines
3.9 KiB
Markdown
182 lines
3.9 KiB
Markdown
Start Here
|
|
===
|
|
|
|
get up and running with dashore incubator development in 5 minutes.
|
|
|
|
prerequisites
|
|
---
|
|
|
|
**required:**
|
|
|
|
- **bun 1.0+** - [bun.sh](https://bun.sh) (`curl -fsSL https://bun.sh/install | bash`)
|
|
- **node.js 18+** - [nodejs.org](https://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
|
|
---
|
|
|
|
```bash
|
|
# 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
|
|
---
|
|
|
|
```bash
|
|
# 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
|
|
---
|
|
|
|
```bash
|
|
# 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
|
|
===
|
|
|
|
```bash
|
|
# 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
|
|
---
|
|
|
|
```bash
|
|
# clear node_modules and reinstall
|
|
rm -rf node_modules .next
|
|
bun install
|
|
```
|
|
|
|
turbopack issues
|
|
---
|
|
|
|
```bash
|
|
# 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
|
|
---
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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!
|