Skip to content

Commit f1fa074

Browse files
yamcodesyamcodes
committed
feat: Introduce custom MDX components for improved documentation of file structures and step-by-step guides, and add fumadocs-typescript.
1 parent f6e4d8c commit f1fa074

File tree

12 files changed

+229
-54
lines changed

12 files changed

+229
-54
lines changed

‎apps/www/content/docs/(architecture)/authentication.mdx‎

Lines changed: 25 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -16,22 +16,39 @@ The `AuthService` is a singleton responsible for:
1616
- Extracting user context from request headers.
1717

1818
### 2. Guarding Routes
19-
Bedstack uses Elysia's `beforeHandle` hook to protect routes. This is implemented in the Controller layer.
2019

21-
```typescript
22-
// src/articles/articles.controller.ts
23-
import { AuthService } from '@/auth/auth.service';
20+
Bedstack uses Elysia hooks to protect routes. Depending on the endpoint, you might require a user to be logged in or simply want to identify them if they are.
2421

25-
const auth = new AuthService();
22+
<Tabs items={['Required Login', 'Optional Login']}>
23+
<Tab value="Required Login">
24+
Use the `requireLogin` middleware to block unauthorized requests.
2625

27-
export const articlesController = new Elysia({ prefix: '/articles' })
28-
.post('/', async ({ body, headers }) => {
29-
const user = await auth.getUserFromHeaders(headers);
26+
```typescript
27+
// articles.controller.ts
28+
new Elysia()
29+
.use(authModule)
30+
.post('/', ({ body, user }) => {
3031
return articlesService.create(body, user.id);
3132
}, {
3233
beforeHandle: [auth.requireLogin]
3334
});
3435
```
36+
</Tab>
37+
<Tab value="Optional Login">
38+
For routes like "Get Articles," you might want to show if a user has favorited an article without requiring them to be logged in.
39+
40+
```typescript
41+
// articles.controller.ts
42+
new Elysia()
43+
.use(authModule)
44+
.get('/', ({ user }) => {
45+
// 'user' might be null here
46+
return articlesService.findAll(user?.id);
47+
});
48+
```
49+
</Tab>
50+
</Tabs>
51+
3552

3653
## Security Design
3754

‎apps/www/content/docs/(architecture)/database.mdx‎

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,28 @@ Drizzle is designed to avoid the overhead typical of large ORMs. It generates cl
5454

5555
## Common Workflows
5656

57-
- **Modify Schema**: Update your `*.schema.ts` file.
58-
- **Generate Migration**: Run `bun run db:generate`.
59-
- **Apply Migration**: Run `bun run db:push` in development or `bun run db:migrate` in production.
57+
<Steps>
58+
<Step>
59+
### Modify Schema
60+
Update your `*.schema.ts` file within the feature folder.
61+
</Step>
62+
<Step>
63+
### Generate Migration
64+
Run the following command to detect changes and generate a new SQL migration file:
65+
```bash terminal
66+
bun run db:generate
67+
```
68+
</Step>
69+
<Step>
70+
### Apply Changes
71+
Apply the migration to your local database:
72+
```bash terminal
73+
bun run db:push
74+
```
75+
</Step>
76+
</Steps>
77+
78+
<Callout type="info">
79+
In production, you should use `bun run db:migrate` which runs the generated SQL files in order against your target database.
80+
</Callout>
81+

‎apps/www/content/docs/(architecture)/getting-started.mdx‎

Lines changed: 26 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -16,22 +16,42 @@ To build a high-performance Bedstack application, we recommend the following too
1616

1717
## Your First Bedstack App
1818

19-
Starting a new Bedstack project is as simple as initializing a Bun project and adding the core dependencies.
19+
Starting a new Bedstack project is straightforward. Follow these steps to initialize your project and adopt the Bedstack pattern:
20+
21+
<Steps>
22+
<Step>
23+
### Initialize your project
24+
25+
Create a new directory and initialize it with Bun.
2026

2127
```bash terminal
2228
mkdir my-bedstack-app
2329
cd my-bedstack-app
2430
bun init
31+
```
32+
</Step>
33+
34+
<Step>
35+
### Add core dependencies
36+
37+
Install the foundational Bedstack tools.
38+
39+
```bash terminal
2540
bun add elysia drizzle-orm arktype
2641
```
42+
</Step>
43+
44+
<Step>
45+
### Adopting the Bedstack Pattern
2746

28-
## Adopting the Pattern
47+
Once your tools are in place, organize your code into the modular, layered structure:
2948

30-
Once your tools are in place, the "Bedstack way" involves organizing your code into a **modular, layered structure**:
49+
1. **Features**: Group your code by domain (e.g., `users`, `products`).
50+
2. **Layers**: Within each feature, separate logic into **Controllers**, **Services**, and **Repositories`.
51+
3. **Types**: Ensure types flow from database schema to API responses.
52+
</Step>
53+
</Steps>
3154

32-
1. **Features**: Group your code by domain (e.g., `users`, `products`) rather than file type.
33-
2. **Layers**: Within each feature, separate your logic into **Controllers**, **Services**, and **Repositories**.
34-
3. **Types**: Ensure your types flow from your database schema all the way to your API responses.
3555

3656
---
3757

‎apps/www/content/docs/(architecture)/project-structure.mdx‎

Lines changed: 40 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -9,45 +9,58 @@ Bedstack follows a **Feature-Based** folder structure. Instead of grouping files
99

1010
Bedstack is designed as a monorepo using **Bun Workspaces** and **Turborepo**.
1111

12-
```bash
13-
.
14-
├── apps
15-
│ ├── api # Your backend application
16-
│ └── www # Your documentation or frontend site
17-
├── packages # Internal packages (shared logic, UI, etc.)
18-
├── bin # Global scripts and CLI tools
19-
└── turbo.json # Turborepo configuration
20-
```
12+
<Files>
13+
<Folder name="apps">
14+
<Folder name="api" description="Your backend application" />
15+
<Folder name="www" description="Your documentation or frontend site" />
16+
</Folder>
17+
<Folder name="packages" description="Internal packages (shared logic, UI, etc.)" />
18+
<Folder name="bin" description="Global scripts and CLI tools" />
19+
<File name="turbo.json" description="Turborepo configuration" />
20+
<File name="bun.lock" />
21+
<File name="package.json" />
22+
</Files>
23+
2124

2225
## Feature Folders
2326

2427
Inside a Bedstack application (like `apps/api`), code is organized into self-contained feature modules. This makes the codebase easier to navigate and allows features to be moved or scaled independently.
2528

2629
### A Typical Feature Structure
2730

28-
```bash
29-
src/users
30-
├── users.controller.ts # REST endpoints
31-
├── users.service.ts # Business logic
32-
├── users.repository.ts # Database access
33-
├── users.mapper.ts # Data transformation
34-
├── schema/
35-
│ └── users.schema.ts # Drizzle table definitions
36-
├── dto/
37-
│ ├── create-user.dto.ts # Input validation (ArkType)
38-
│ └── user.dto.ts # Output shape
39-
└── interfaces/
40-
├── user.interface.ts # Domain model
41-
└── user-row.ts # Database row type
42-
```
31+
<Files>
32+
<Folder name="src/users" defaultOpen>
33+
<File name="users.controller.ts" description="REST endpoints" />
34+
<File name="users.service.ts" description="Business logic" />
35+
<File name="users.repository.ts" description="Database access" />
36+
<File name="users.mapper.ts" description="Data transformation" />
37+
<Folder name="schema">
38+
<File name="users.schema.ts" description="Drizzle table definitions" />
39+
</Folder>
40+
<Folder name="dto">
41+
<File name="create-user.dto.ts" description="Input validation (ArkType)" />
42+
<File name="user.dto.ts" description="Output shape" />
43+
</Folder>
44+
<Folder name="interfaces">
45+
<File name="user.interface.ts" description="Domain model" />
46+
<File name="user-row.ts" description="Database row type" />
47+
</Folder>
48+
</Folder>
49+
</Files>
50+
4351

4452
## The `shared` Folder
4553

4654
Global utilities, shared middleware, and cross-cutting concerns live in the `src/shared` directory.
4755

48-
- **`shared/constants`**: Global constants (auth, validation, etc.).
49-
- **`shared/errors`**: Global error types and factories.
50-
- **`shared/utils`**: Pure utility functions used app-wide.
56+
<Files>
57+
<Folder name="src/shared" defaultOpen>
58+
<Folder name="constants" description="Global constants (auth, validation, etc.)" />
59+
<Folder name="errors" description="Global error types and factories" />
60+
<Folder name="utils" description="Pure utility functions used app-wide" />
61+
</Folder>
62+
</Files>
63+
5164

5265
> **Tip**: Avoid dumping everything into `shared`. If a utility or constant is only used in one feature, keep it inside that feature's folder.
5366

‎apps/www/content/docs/(architecture)/validation.mdx‎

Lines changed: 22 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,20 +10,38 @@ In Bedstack, validation is not just an afterthought—it's a core part of the ar
1010
Data Transfer Objects (DTOs) define the shape of data entering and leaving your application. In Bedstack, every DTO is an **ArkType** schema.
1111

1212
### Defining an Input DTO
13-
Input DTOs are used in `POST`, `PUT`, and `PATCH` requests to validate the request body.
13+
14+
Input DTOs are used in `POST`, `PUT`, and `PATCH` requests. ArkType allows you to define these using a concise string-based syntax or a more traditional object-based one.
15+
16+
<Tabs items={['Simple Schema', 'Detailed Schema']}>
17+
<Tab value="Simple Schema">
18+
The string-based syntax is perfect for quickly defining shapes.
1419

1520
```typescript
16-
// src/posts/dto/create-post.dto.ts
1721
import { type } from 'arktype';
1822

1923
export const CreatePostDto = type({
2024
title: 'string >= 3',
2125
content: 'string',
22-
'tags?': 'string[]', // ? denotes optional
26+
'tags?': 'string[]',
2327
});
28+
```
29+
</Tab>
30+
<Tab value="Detailed Schema">
31+
For complex rules and documentation, use the chained API.
2432

25-
export type CreatePostDto = typeof CreatePostDto.infer;
33+
```typescript
34+
import { type } from 'arktype';
35+
36+
export const CreatePostDto = type({
37+
title: type('string').and('3 <= length <= 100'),
38+
content: 'string',
39+
'tags?': 'string[]',
40+
}).describe('A schema for creating a new post');
2641
```
42+
</Tab>
43+
</Tabs>
44+
2745

2846
## Validation at the Edge
2947

‎apps/www/content/docs/(architecture)/what-is-bedstack.mdx‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,3 +32,20 @@ The selected technologies share Bedstack's core philosophy:
3232
Bedstack is unapologetically opinionated. A tech stack is not just a menu of options; it is a curated path. We've selected these tools because they reinforce each other to create a developer experience that is both fast and safe.
3333

3434
Whether you are building a small MVP or a large-scale production system, the **Bedstack Architecture** provides the structure you need to move fast without breaking things.
35+
36+
---
37+
38+
## FAQ
39+
40+
<Accordions>
41+
<Accordion title="Can I use Bedstack with Node.js?">
42+
Bedstack is designed specifically for **Bun**. While most of the tools (Elysia, Drizzle, ArkType) work on Node.js, the core philosophy of Bedstack—unmatched speed and zero-boilerplate—is best achieved using the Bun runtime.
43+
</Accordion>
44+
<Accordion title="How does it compare to NestJS?">
45+
Bedstack is heavily inspired by NestJS's modular and layered architecture but aims for **minimal friction**. We avoid heavy use of decorators and complex dependency injection, favoring clean TypeScript patterns and the performance of the Bun ecosystem.
46+
</Accordion>
47+
<Accordion title="Is it production ready?">
48+
Yes! Our [RealWorld example implementation](/docs/realworld) is a non-trivial, production-scale application that demonstrates how Bedstack handles real-world complexity, authentication, and database relationships.
49+
</Accordion>
50+
</Accordions>
51+

‎apps/www/content/docs/realworld/development.mdx‎

Lines changed: 19 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,25 @@ Developing on the Conduit app is designed to be fast. This guide covers the esse
77

88
## Development Workflow
99

10-
1. **Watch Mode**: Run `bun run --cwd apps/conduit dev` to start the app with auto-reloading.
11-
2. **Linting & Formatting**: We use **Biome**. Run `bun run fix` from the root to automatically fix issues.
12-
3. **Database Changes**: If you modify a `*.schema.ts` file:
13-
- Run `bun run --cwd apps/conduit db:generate` to create a migration.
14-
- Run `bun run --cwd apps/conduit db:push` to apply it.
10+
<Steps>
11+
<Step>
12+
### Watch Mode
13+
Run `bun run --cwd apps/conduit dev` to start the app with auto-reloading.
14+
</Step>
15+
16+
<Step>
17+
### Linting & Formatting
18+
We use **Biome**. Run `bun run fix` from the root to automatically fix issues.
19+
</Step>
20+
21+
<Step>
22+
### Database Changes
23+
If you modify a `*.schema.ts` file:
24+
- Run `bun run --cwd apps/conduit db:generate` to create a migration.
25+
- Run `bun run --cwd apps/conduit db:push` to apply it.
26+
</Step>
27+
</Steps>
28+
1529

1630
## Testing Strategy
1731

‎apps/www/content/docs/realworld/setup.mdx‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ Ensure you have the following installed on your machine:
1313
- **[Docker](https://www.docker.com/)** (for running the PostgreSQL database)
1414
- **[Git](https://git-scm.com/)**
1515

16+
<Steps>
17+
<Step>
1618
## 1. Clone the Repository
1719

1820
Clone the Bedstack monorepo which contains the `conduit` application:
@@ -21,23 +23,29 @@ Clone the Bedstack monorepo which contains the `conduit` application:
2123
git clone https://github.com/yamcodes/bedstack.git
2224
cd bedstack
2325
```
26+
</Step>
2427

28+
<Step>
2529
## 2. Install Dependencies
2630

2731
Bedstack uses Bun's built-in package manager. Run the following command in the root directory:
2832

2933
```bash terminal
3034
bun install
3135
```
36+
</Step>
3237

38+
<Step>
3339
## 3. Environment Variables
3440

3541
The application requires some environment variables to connect to the database and sign JWTs. Copy the example file:
3642

3743
```bash terminal
3844
cp apps/conduit/.env.example apps/conduit/.env
3945
```
46+
</Step>
4047

48+
<Step>
4149
## 4. Database Setup
4250

4351
We use Docker Compose to spin up a local PostgreSQL instance.
@@ -56,7 +64,9 @@ bun run --cwd apps/conduit db:push
5664
# Seed with initial data
5765
bun run --cwd apps/conduit db:seed
5866
```
67+
</Step>
5968

69+
<Step>
6070
## 5. Run the Application
6171

6272
Now you can start the development server:
@@ -66,3 +76,6 @@ bun run --cwd apps/conduit dev
6676
```
6777

6878
The API is now available at `http://localhost:3000/api`. You can also visit `http://localhost:3000/swagger` to explore the interactive API documentation.
79+
</Step>
80+
</Steps>
81+

‎apps/www/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
"clsx": "^2.1.1",
2121
"fumadocs-core": "16.4.7",
2222
"fumadocs-mdx": "14.2.5",
23+
"fumadocs-typescript": "^5.0.1",
2324
"fumadocs-ui": "16.4.7",
2425
"lucide-react": "^0.562.0",
2526
"next": "16.1.1",

‎apps/www/source.config.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { remarkMdxFiles } from 'fumadocs-core/mdx-plugins/remark-mdx-files';
12
import {
23
defineConfig,
34
defineDocs,
@@ -22,6 +23,6 @@ export const docs = defineDocs({
2223

2324
export default defineConfig({
2425
mdxOptions: {
25-
// MDX options
26+
remarkPlugins: [remarkMdxFiles],
2627
},
2728
});

0 commit comments

Comments
 (0)