1 Getting Started
koyo comes with a command line utility which you can use to get started quickly.
Running raco koyo new <project-name> from the command line will get you set up with a basic web application. From there, you should follow the instructions in the generated "README.md" file and take a look at the generated source code.
You can then use raco koyo serve to run your application, although, generally, it’s more convenient to use chief (which iself runs raco koyo serve based on the configuration in "Procfile") in order to be able to both compile your assets and run the web server from a single terminal session.
1.1 Project Structure
Running raco koyo new example generates the following project structure in the current directory:
Folder |
| Description |
"example/" |
| Contains all the application logic. |
"example-tests/" |
| Contains tests for all of the distinct components in the application. |
"migrations/" |
| Database schema migrations go in here. |
"resources/" |
| Various "data" files go in here, including translations, stylesheets, images and javascripts. |
"static/" |
| Assets compiled by the asset pipeline go in here. Not committed to source control. |
File |
| Description |
".env.default" |
| A list of default environment variables for your application. Generally committed to source control. |
".nvmrc" |
| Contains the node version required to work on your application. This is used by nvm to set up the environment appropriately for that respective version. |
"build.mjs" |
| The bundler (esbuild) script. Describes how (and which) assets are to be preprocessed before being copied into the static/ folder. |
"Procfile" |
| The process configuration file. Used by chief to determine which processes to run when it starts a development server. By default, it runs a process to build the assets on change and the application web server. |
"package.json" |
| Describes the node dependencies for the asset pipeline. |
The application folder is further subdivided into:
Folder |
| Description |
"pages/" |
| Contains the implementation for every page in your application (the presentation). |
"components/" |
| Contains the implementation for every bit of business logic in your application. |
File |
| Description |
"config.rkt" |
| Contains all of the application's configuration options. |
"dynamic.rkt" |
| The main entrypoint for the application. Everything gets wired together in this file. |
"info.rkt" |
| Describes the package that makes up your application and its dependencies. |
1.2 Interactive Console
Running raco koyo console from within the root of a koyo application starts an interactive REPL with that application’s components loaded into scope.
Components are accessible via system-ref. For example, if you have a component named database then you can access it from the console using (system-ref 'database).
The start and stop procedures can be used to start and, respectively, stop the system from the console. The start procedure is implicitly called at the beginning of every console session.
See start-console-here for information on loading the console functionality into an existing REPL session.