updated docs

Author: realtux

docs/docs/getting-started/quickstart.md

@@ -4,7 +4,9 @@ sidebar_position: 1
 
 # quickstart
 
-## using node.js
+## initialization
+
+### with node.js
 
 ```sh
 # create a new directory for your project
@@ -24,7 +26,7 @@ npm start
 
 initializing will create the exa.js template project structure in the current directory.
 
-## using bun
+### with bun
 
 ```bash
 # create a new directory for your project
@@ -43,3 +45,24 @@ bun run start
 ```
 
 initializing will create the exa.js template project structure in the current directory.
+
+## usage
+
+after starting, your terminal should show some startup information such as:
+
+```bash
+exa.js by tux - v0.0.17
+-----------------------------
+2024-12-23T23:09:26.400-06:00
+-----------------------------
+mode: development
+server running on 0.0.0.0:8118
+```
+
+depending on which modules are enabled, there may be some additional output.
+
+the seed project created after initialization has an api route `/api/hello/world` created. to see its output, run
+
+```bash
+curl http://127.0.0.1:8118/api/hello/world
+```

docs/docs/intro.md

@@ -1,13 +1,38 @@
 ---
 sidebar_position: 1
+sidebar_label: introduction
 ---
 
-# welcome
-
-## what is exa.js?
+# exa.js
 
 exa.js is a minimal node.js backend framework that has a strong focus on simplicity, modularity, and convention over configuration. it makes available the most important stuff needed for a node.js web framework, and nothing more.
 
-## motivation
+## javascript's 10,000th framework
 
 as if the javascript ecosystem needs another framework... i get it, but please know that this project is the culmination of ~10 years of professional development trying to understand what i/people really need in a framework. this project is the consolidated and cleaned up version of about 30 projects worth of boilerplate patchwork that has been unevenly iterated on and used in some form during this time. i'm certain you'll find use for it, and i certainly will.
+
+## requirements
+
+- node.js v10+
+- optional: bun
+- optional: docker
+
+## get going in the next two minutes
+
+```bash
+# create a new directory for your project
+mkdir myproject; cd myproject
+
+# initialize
+npx @exajs/core init
+
+# start dev with auto reload
+npm run watch
+
+# test
+curl http://127.0.0.1:8118/api/hello/world
+```
+
+## contributing
+
+this project needs testing and bug fixes more than anything else. it also needs expansion of the core library of helper code.

docs/docs/modules/migrations.md

@@ -0,0 +1,34 @@
+---
+sidebar_position: 10
+---
+
+# migrations
+
+the purpose of migrations is to easily apply and rollback changes to a database in a way that will sync across workspaces and developers. although not technically a module since `exa.js` has no internal code associated with migrations, it's included as a recommended way of handling database migrations anyway. the `migrations` directory could also be used with other tools, if so desired.
+
+## jmig
+
+the suggested migration tool and the one this documentation will focus on is `jmig`. the full documentation for this tool is located at [https://github.com/realtux/jmig](https://github.com/realtux/jmig). `jmig` is invoked in an `exa.js` project via `npx`.
+
+## managing migrations
+
+migration files are created in the `migrations` folder using the jmig command `npx jmig create <migration name>`. to create a migration file like the one in the next section, you could run `npx jmig create initial tables`. after the migration file is filled out, the changes can be applied with `npx jmig migrate`. changes can be rolled back with `npx jmig rollback`.
+
+## sample migration file
+
+```sql title="migrations/20240417195942-initial-tables.sql"
+up:
+create table users (
+    user_id int unsigned primary key auto_increment,
+    name varchar(64) not null,
+    email varchar(64) not null,
+    created_at datetime not null
+) character set utf8mb4 collate utf8mb4_unicode_ci;
+
+down:
+drop table users;
+```
+
+### how to interpret
+
+a blank migration file will have only `up:` and `down:` in it to start. changes to a database should be placed under the `up:` section, then reversing those changes should be placed in the `down:`. in the provided example, a `users` table is created upon migration, and then dropped upon rollback.

docs/docusaurus.config.js

@@ -48,7 +48,7 @@ const config = {
                     // Please change this to your repo.
                     // Remove this to remove the "edit this page" links.
                     editUrl:
-                        'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
+                        'https://github.com/realtux/exa/tree/master/docs',
                 },
                 blog: {
                     showReadingTime: true,
@@ -59,7 +59,7 @@ const config = {
                     // Please change this to your repo.
                     // Remove this to remove the "edit this page" links.
                     editUrl:
-                        'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
+                        'https://github.com/realtux/exa/tree/master/docs',
                     // Useful options to enforce blogging best practices
                     onInlineTags: 'warn',
                     onInlineAuthors: 'warn',
@@ -92,7 +92,7 @@ const config = {
             navbar: {
                 title: 'exa.js',
                 logo: {
-                    alt: 'My Site Logo',
+                    alt: 'exa.js',
                     src: 'img/logo.svg',
                 },
                 items: [
@@ -104,7 +104,7 @@ const config = {
                     },
                     {
                         href: 'https://github.com/realtux/exa',
-                        label: 'GitHub',
+                        label: 'github',
                         position: 'right',
                     },
                 ],

var/template/migrations/20240417195942-initial-tables.sql

@@ -1,4 +1,10 @@
 up:
-
+create table users (
+    user_id int unsigned primary key auto_increment,
+    name varchar(64) not null,
+    email varchar(64) not null,
+    created_at datetime not null
+) character set utf8mb4 collate utf8mb4_unicode_ci;
 
 down:
+drop table users;