Skip to content

Commit 33fb443

Browse files
LibirSoftLibirSoft
authored
Merge pull request #10 from AsenaJs/develop
Ulak documentation added
2 parents 9bfa58d + 9daa662 commit 33fb443

File tree

11 files changed

+1113
-79
lines changed

11 files changed

+1113
-79
lines changed

‎.vitepress/config.mts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,13 +25,15 @@ export default defineConfig({
2525
{text: "Examples", link: "/docs/examples"},
2626
{text: "Showcase", link: "/docs/showcase"},
2727
{text: "Roadmap", link: "/docs/roadmap"},
28+
{text: "LLM.txt", link: "/llm.txt"},
2829
],
2930

3031
sidebar: [
3132
{text: "Quick Start", link: "/docs/get-started"},
3233
{text: "Examples", link: "/docs/examples"},
3334
{text: "Showcase", link: "/docs/showcase"},
3435
{text: "Roadmap", link: "/docs/roadmap"},
36+
{text: "📄 LLM.txt", link: "/llm.txt"},
3537
{
3638
text: "Concepts",
3739
items: [
@@ -42,6 +44,7 @@ export default defineConfig({
4244
{text: "Context", link: "/docs/concepts/context"},
4345
{text: "Validation", link: "/docs/concepts/validation"},
4446
{text: "WebSocket", link: "/docs/concepts/websocket"},
47+
{text: "Ulak", link: "/docs/concepts/ulak"},
4548
],
4649
},
4750
{

‎docs/cli/commands.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -356,7 +356,7 @@ Output: dist/index.js
356356
::: tip Production Deployment
357357
After building, you can run your application with:
358358
```bash
359-
bun dist/index.js
359+
bun dist/index.asena.js
360360
```
361361
:::
362362

‎docs/cli/configuration.md‎

Lines changed: 137 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,19 @@ export default defineConfig({
2828
interface AsenaConfig {
2929
sourceFolder: string; // Source code directory
3030
rootFile: string; // Application entry point
31-
buildOptions: BuildOptions; // Bun bundler options
31+
buildOptions?: BuildOptions; // Optional Bun bundler options
3232
}
33+
34+
/**
35+
* BuildOptions is a subset of Bun's BuildConfig.
36+
* Only backend-relevant options are exposed.
37+
*/
38+
type BuildOptions = Partial<
39+
Pick<
40+
Bun.BuildConfig,
41+
'outdir' | 'sourcemap' | 'minify' | 'external' | 'format' | 'drop'
42+
>
43+
>;
3344
```
3445

3546
## Default Configuration
@@ -44,12 +55,11 @@ export default defineConfig({
4455
rootFile: 'src/index.ts',
4556
buildOptions: {
4657
outdir: 'dist',
47-
sourcemap: 'linked',
48-
target: 'bun',
4958
minify: {
5059
whitespace: true,
5160
syntax: true,
52-
identifiers: false,
61+
identifiers: false, //It's better for you to make this false for better debugging during the running phase of the application.
62+
keepNames: true
5363
},
5464
},
5565
});
@@ -113,10 +123,22 @@ await server.start();
113123

114124
### buildOptions
115125

116-
**Type:** `BuildOptions`
117-
**Default:** See below
126+
**Type:** `BuildOptions` (optional)
127+
**Default:** `{ outdir: './out' }` if not specified
118128

119-
Configuration options for Bun's bundler. Asena supports all Bun bundler options.
129+
Configuration options for Bun's bundler. Asena exposes only backend-relevant build options from Bun's `BuildConfig`.
130+
131+
::: info Managed Internally
132+
The `entrypoints` and `target` properties are managed internally by Asena CLI and cannot be configured by users. Asena always builds for the `bun` target since it's a Bun-native backend framework.
133+
:::
134+
135+
**Available BuildOptions:**
136+
- `outdir` - Output directory for compiled files
137+
- `sourcemap` - Source map generation strategy
138+
- `minify` - Code minification options
139+
- `external` - Dependencies to exclude from bundling
140+
- `format` - Output module format (ESM/CJS)
141+
- `drop` - Remove function calls from bundle (e.g., `console`, `debugger`)
120142

121143
## Build Options Reference
122144

@@ -138,7 +160,7 @@ export default defineConfig({
138160
### sourcemap
139161

140162
**Type:** `'none' | 'inline' | 'external' | 'linked'`
141-
**Default:** `'linked'`
163+
**Default:** Not set (optional)
142164

143165
Controls source map generation for debugging:
144166

@@ -160,25 +182,92 @@ export default defineConfig({
160182
- **Production:** Use `'none'` for smaller bundle size
161183
:::
162184

163-
### target
185+
### format
186+
187+
**Type:** `'esm' | 'cjs'`
188+
**Default:** `'esm'` (Bun's default)
189+
190+
Specifies the output module format.
191+
192+
```typescript
193+
export default defineConfig({
194+
buildOptions: {
195+
format: 'esm', // ES modules (recommended for Bun)
196+
},
197+
});
198+
```
199+
200+
::: tip
201+
Asena works best with ESM format since Bun has native ESM support. CJS is supported but not recommended unless you have specific compatibility requirements.
202+
:::
203+
204+
### external
205+
206+
**Type:** `string[]`
207+
**Default:** `[]` (empty array)
208+
209+
List of dependencies that should not be bundled into the output. Useful for native modules or dependencies that should be resolved at runtime.
210+
211+
```typescript
212+
export default defineConfig({
213+
buildOptions: {
214+
external: ['pg', 'mysql2', 'better-sqlite3'], // Don't bundle database drivers
215+
},
216+
});
217+
```
218+
219+
**Common use cases:**
220+
- Native Node.js modules (e.g., `fs`, `path` - though Bun handles these)
221+
- Database drivers with native bindings
222+
- Large dependencies that should be installed separately
223+
224+
::: warning Native Dependencies
225+
Some packages with native bindings (like `better-sqlite3`) must be marked as external to work correctly.
226+
:::
227+
228+
### drop
164229

165-
**Type:** `'bun' | 'node' | 'browser'`
166-
**Default:** `'bun'`
230+
**Type:** `string[]`
231+
**Default:** `[]` (empty array)
167232

168-
Specifies the compilation target runtime.
233+
Removes specified function calls from the bundle during build. Commonly used to strip debugging code in production.
169234

170235
```typescript
171236
export default defineConfig({
172237
buildOptions: {
173-
target: 'bun', // Optimize for Bun runtime
238+
drop: ['console', 'debugger'], // Remove all console calls and debugger statements
239+
},
240+
});
241+
```
242+
243+
**Common values:**
244+
- `'console'` - Removes all `console.*` calls
245+
- `'debugger'` - Removes `debugger` statements
246+
- Custom identifiers like `'logger.debug'`
247+
248+
::: danger Side Effects Warning
249+
The `drop` option removes the entire call expression, including arguments, even if they have side effects. For example, `drop: ['console']` will turn `console.log(doSomething())` into nothing, so `doSomething()` will never execute.
250+
:::
251+
252+
**Example - Production build:**
253+
254+
```typescript
255+
export default defineConfig({
256+
sourceFolder: 'src',
257+
rootFile: 'src/index.ts',
258+
buildOptions: {
259+
outdir: 'dist',
260+
sourcemap: 'none',
261+
minify: true,
262+
drop: ['console', 'debugger'], // Clean production output
174263
},
175264
});
176265
```
177266

178267
### minify
179268

180269
**Type:** `boolean | MinifyOptions`
181-
**Default:** `{ whitespace: true, syntax: true, identifiers: false }`
270+
**Default:** `{ whitespace: true, syntax: true, identifiers: false, keepNames: true }`
182271

183272
Controls code minification for smaller bundle sizes.
184273

@@ -201,6 +290,7 @@ export default defineConfig({
201290
whitespace: true, // Remove unnecessary whitespace
202291
syntax: true, // Apply smart condensation transforms
203292
identifiers: false, // Keep original variable/function names
293+
keepNames: true // Preserve function and class names
204294
},
205295
},
206296
});
@@ -213,6 +303,7 @@ export default defineConfig({
213303
| `whitespace` | `boolean` | Removes unnecessary whitespace and newlines |
214304
| `syntax` | `boolean` | Applies syntax-level optimizations |
215305
| `identifiers` | `boolean` | Renames variables/functions to shorter names |
306+
| `keepNames` | `boolean` | Preserves function and class names for debugging |
216307

217308
::: warning identifiers and Debugging
218309
Setting `identifiers: true` makes debugging harder because:
@@ -239,12 +330,12 @@ export default defineConfig({
239330
buildOptions: {
240331
outdir: 'dist',
241332
sourcemap: 'linked', // Full debugging support
242-
target: 'bun',
243333
minify: {
244334
whitespace: false, // Keep readable
245335
syntax: false,
246336
identifiers: false, // Keep original names
247337
},
338+
drop: [], // Keep all console logs for debugging
248339
},
249340
});
250341
```
@@ -261,12 +352,12 @@ export default defineConfig({
261352
buildOptions: {
262353
outdir: 'dist',
263354
sourcemap: 'none', // No source maps
264-
target: 'bun',
265355
minify: {
266356
whitespace: true, // Minimize size
267357
syntax: true,
268358
identifiers: true, // Shorten names
269359
},
360+
drop: ['console', 'debugger'], // Remove debugging code
270361
},
271362
});
272363
```
@@ -285,7 +376,7 @@ asena build
285376

286377
## Advanced Build Options
287378

288-
Asena supports all Bun bundler options. Here are some common advanced configurations:
379+
Asena exposes backend-relevant build options from Bun's bundler. Here are some common advanced configurations:
289380

290381
### Custom Entry Points
291382

@@ -299,16 +390,18 @@ export default defineConfig({
299390
});
300391
```
301392

302-
### Multiple Output Formats
393+
### Production-Optimized Build
303394

304395
```typescript
305396
export default defineConfig({
306397
sourceFolder: 'src',
307398
rootFile: 'src/index.ts',
308399
buildOptions: {
309400
outdir: 'dist',
310-
format: 'esm', // Output as ES modules
311-
splitting: true, // Code splitting
401+
format: 'esm',
402+
sourcemap: 'none',
403+
minify: true,
404+
drop: ['console', 'debugger'], // Strip debugging code
312405
},
313406
});
314407
```
@@ -321,7 +414,7 @@ export default defineConfig({
321414
rootFile: 'src/index.ts',
322415
buildOptions: {
323416
outdir: 'dist',
324-
external: ['pg', 'mysql2'], // Don't bundle these
417+
external: ['pg', 'mysql2', 'better-sqlite3'], // Don't bundle native modules
325418
},
326419
});
327420
```
@@ -353,7 +446,7 @@ export default defineConfig({
353446
buildOptions: {
354447
outdir: 'packages/api/dist',
355448
sourcemap: 'linked',
356-
target: 'bun',
449+
format: 'esm',
357450
},
358451
});
359452
```
@@ -369,29 +462,36 @@ export default defineConfig({
369462
buildOptions: {
370463
outdir: '/app/dist',
371464
sourcemap: 'none',
372-
target: 'bun',
373465
minify: true,
466+
drop: ['console', 'debugger'], // Clean production logs
374467
},
375468
});
376469
```
377470

378471
## Bun Bundler Options
379472

380-
Asena uses Bun's bundler under the hood. For complete bundler options, see the [Bun Bundler Documentation](https://bun.sh/docs/bundler).
473+
Asena uses Bun's bundler under the hood and exposes only the options relevant for backend framework builds.
474+
475+
::: info
476+
The `entrypoints` and `target` are managed internally by Asena CLI. All exposed options are **optional** (wrapped in `Partial<>`).
477+
:::
478+
479+
**Supported BuildOptions:**
480+
481+
| Option | Type | Description | Reference |
482+
|:--------------|:----------------------|:-------------------------------------------------|:---------------------------------------------------------|
483+
| `outdir` | `string` | Output directory for compiled files | [Bun Docs](https://bun.com/docs/bundler#outdir) |
484+
| `sourcemap` | `'none' \| 'inline' \| 'external' \| 'linked'` | Source map generation strategy | [Bun Docs](https://bun.com/docs/bundler#sourcemap) |
485+
| `minify` | `boolean \| MinifyOptions` | Code minification options | [Bun Docs](https://bun.com/docs/bundler#minify) |
486+
| `external` | `string[]` | Dependencies to exclude from bundling | [Bun Docs](https://bun.com/docs/bundler#external) |
487+
| `format` | `'esm' \| 'cjs'` | Output module format | [Bun Docs](https://bun.com/docs/bundler#format) |
488+
| `drop` | `string[]` | Remove function calls (e.g., `console`, `debugger`) | [Bun Docs](https://bun.com/docs/bundler#drop) |
381489

382-
**Common Options:**
490+
::: warning Unsupported Options
491+
Options like `target`, `entrypoints`, `splitting`, `define`, and `loader` are **not exposed** because they're either managed internally or not relevant for backend framework builds.
492+
:::
383493

384-
| Option | Type | Description |
385-
|:--------------|:----------------------|:-------------------------------------|
386-
| `outdir` | `string` | Output directory |
387-
| `sourcemap` | `string` | Source map generation |
388-
| `target` | `string` | Compilation target |
389-
| `minify` | `boolean \| object` | Code minification |
390-
| `format` | `'esm' \| 'cjs'` | Output format |
391-
| `splitting` | `boolean` | Code splitting |
392-
| `external` | `string[]` | External dependencies |
393-
| `define` | `Record<string, string>` | Define constants |
394-
| `loader` | `Record<string, string>` | File loaders |
494+
For a complete reference of Bun's bundler capabilities, see the [Bun Bundler Documentation](https://bun.com/docs/bundler).
395495

396496
## Best Practices
397497

@@ -492,7 +592,7 @@ export default defineConfig({
492592
- [CLI Commands](/docs/cli/commands) - Available CLI commands
493593
- [CLI Examples](/docs/cli/examples) - See project structure examples
494594
- [Deployment](/docs/guides/deployment) - Production deployment
495-
- [Bun Bundler](https://bun.sh/docs/bundler) - Complete bundler reference
595+
- [Bun Bundler](https://bun.com/docs/bundler) - Complete bundler reference
496596

497597
---
498598

‎docs/cli/examples.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -345,7 +345,7 @@ The build files are in the `dist/` directory (configured in `asena.config.ts`).
345345
Run the production build:
346346

347347
```bash
348-
bun dist/index.js
348+
bun dist/index.asena.js
349349
```
350350

351351
::: tip Build Output

0 commit comments

Comments
 (0)