Carolina is a web development framework in Node.js. It is a thin framework, consisting mostly of my favorite NPM modules for each relevant aspect, and defining a system for organizing a web application into mini apps.
To start a new Carolina project, use the generator:
npx @carolina.js/generator "My New Project"
That would create the project directory my-new-project/,
with some starter files in it.
To get everything working, you will need to install dependencies and then
copy some files from some Carolina apps into your workspace. You can do
this with init.sh.
cd my-new-project/
bash init.sh
You should then be able to run a server on http://localhost:8080 using the
following command:
npm start
Before going further, you should get familiar with the project files that were created.
Your new project structure looks something like this (this is called your project directory):
my-new-project/
assets/ # static assets go here (will be available at /assets)
config/ # configuration files for each app
files/ # logs and other stuff here (ignored by .gitignore)
main/ # your main app files (service, routes, etc)
scripts/ # place for scripts, including run-server.js
src/ # place for front-end source files (including AdminBro components)
templates/ # Place for .pug templates (and other templates as needed)
.gitignore # files to ingore when using .git
index.js # entry point for running CLI commands within your project
init.sh # initialization script
package.json # NPM file listing dependencies, etc
Your Carolina application is made of of "apps", which are listed in your
main configuration file config/app.js.
Each app has a name and consists a service object. It also interacts with other
apps and probably provides a way for other apps to interact with it. For example,
the "publish" app, which is responsible for copying files from apps to your
project directory (this was done in init.sh), defines CLI commands with
"cli" app. The "publish" app also provides a way for other apps (including
custom ones) to register that some files from the app (templates, assets, etc)
should be copyable into a project directory.
The apps are listed as an object mapping names (which you should not change)
to require paths. That paths should either be paths within node_modules or
local paths from the perspective of your project directory
(starting with './'). The destination must be a Carolina-compliant app
directory (which is described in a later section). All Carolina apps are this
way, as is your project's main/ directory.
In addition to config/app.js, the config/ directory contains other config
files. Note that the names of those files match the names of some of your
apps. Not all apps have config files. The service of the "config" app will
track all configuration files in the config/ directory if the name of
the config file matches an app name. Many of the config files read from
your project's .env file and check for values if they exist.
The project's main/ directory is a Carolina App. In index.js it provides
a service, which extends BaseService from @carolina/core/app. You can add
methods to that service to handle application logic.
A router.js file is also defined. This defines an
express router, which
by default will be mounted at '/'. You can add routes and edit this router
as needed. You can also define other files in this directory, which will be
documented in the sections on the various apps.
If your project grows, it doesn't make sense to have everything you do be
under the "main" app. You can create other apps, and put them under the
apps/ directory. More on defining custom apps is in a later section.
You may have noticed that the main handler for your router renders a
template called "home". That is a reference to the file templates/home.pug.
The express application created by the "routes" app already defines
templates/ as your default template directory and 'pug' as the default
template language. The template directory can be swapped by changing the
configuration values in config/disk.js.
You can edit templates/home.pug to edit your site's landing page.
The next few sections of this documentation provide an overview of the framework, including an introduction to writing custom apps.
The "Apps" section is the main part of the documentation. It provides information on each Carolina app, including:
The available interactions will be important from the perspective of writing
your application. For example, the "cli" app will read cli.js from
any installed app (including your "main" app and any custom apps) and
look for an exported parser (an instance of
argparse). If it exists, it will
be added to the CLI accessible at index.js. For another example, any
app can export an express router from routes.js (your "main" app
already does this). The "routes" app will find this and it will be mountable
to your web application.
The next sections provide some information on services and the application lifecycle.