CAROLINA DOCS

---

Custom Apps

The Main App

In addition to the apps included in the framework, the main/ directory in your project is an app. An app in a node module that defines a service as a subclass of BaseService in its index.js file. Optionally, other files in the app directory are integrations with other apps (defining CLI commands, database models, admin panel configurations, express middleware and routes, etc). In order for to be managed by the App instance, it must be listed in config/app.js.

The "main" app is where your custom code specific to you application belongs. For small projects, there may not need to be any other apps. If it grows, you should define other apps in apps/. Each app should be written so it is theoretically re-usable in other projects.

Your integration files (model.js, cli.js, routes.js) are read by other apps, so you shouldn't import them in your service file. If you want to break up your code, apps won't integrate files starting with a "_", so you can safely use files like _functions.js within your app. Also, every app including custom ones should document what files they will read, so you can safely use any other files.

App Structure

You should write custom apps the same way you write the main app.

Here is an example file structure for a custom app:

apps/
  my_custom_app/
    index.js        # service class definition
    cli.js          # defines CLI commands
    models.js       # defines database models 
    middleware.js   # express middleware
    router.js       # express router

The apps/my_custom_app/ works just like main/.

You could reorganize to define models and routers in multiple files:

apps/
  my_custom_app/
    models/
      index.js    # exports all models (after importing them from Page and Post)
      page.js     # defines a Page schema
      post.js     # defines a Post schema
    router/
      index.js      # exports an express router consisting of the other two
      browser.js    # exports a router for browser access
      api.js        # exports a router for api access
    index.js        # service class
    cli.js          # CLI commands
    middleware.js   # express middleware
    _functions.js   # function library used by the service

Registering Apps

To register your app with the App instance, add it to the apps object in config/apps.js:

const apps = {

  // carolina apps

  // add custom apps here
  my_custom_app: './apps/my_custom_app',

  main: './main'
};

Using Custom Apps

You can then access your custom app the same way you would access any other. The integrations (models, etc) will be loaded by their services.

router.get('/', asyncHandler(async(req, res) => {
  // get model from your custom app
  const Page = App.$db.model('Page'); 
  // access your custom service
  const MyCustomService = App.$my_custom_app;
}));

---

CAROLINA DOCS