Anatomy of a Gingee App

Every application built on Gingee follows a simple and consistent structure. This guide breaks down that structure, explains the critical role of the box folder, and provides a comprehensive reference for all the settings available in the app.json and routes.json configuration file.

App Folder Structure

Every first-level directory inside your server's web root is considered a distinct App. For an application named my_app, the structure looks like this:

web/
└── my_app/
    ├── box/
    ├── css/
    ├── images/
    ├── scripts/
    └── index.html

The Importance of the box Folder

The box folder is the private, secure core of your application. It contains all your backend logic, configuration, and private data.

The app.json File:

The app.json file, located at web/my_app/box/app.json, is the central configuration file for your application. It tells the Gingee server how to handle the app, what resources it needs, and how it should behave.

Here is a comprehensive breakdown of all available properties.

{
  "name": "My Awesome App",
  "description": "This is a demonstration of all app.json settings.",
  "version": "1.2.0",
  "type": "MPA",
  "mode": "production",
  "spa": {
    "enabled": false,
    "dev_server_proxy": "http://localhost:5173",
    "build_path": "./dist",
    "fallback_path": "index.html"
  },
  "db": [],
  "startup_scripts": [],
  "default_include": [],
  "env": {},
  "jwt_secret": "a-very-strong-and-unique-secret-key",
  "cache": {
    "client": {
      "enabled": true,
      "no_cache_regex": ["/api/realtime"]
    },
    "server": {
      "enabled": true,
      "no_cache_regex": ["/api/dynamic-script.js"]
    }
  }
}

Core Metadata

Application Type & Mode

SPA Configuration (spa object)

This object is only used when app is of "type": "SPA".

Database Connections

Script Execution Configuration

Cache

The pmft.json File (Permissions Manifest)

If you plan to distribute your application as a .gin package, you must declare the permissions it requires in a pmft.json file. This manifest is read by the gingee-cli during the installation process to request consent from the server administrator.

For a complete guide on the permissions system and the structure of this file, please see the Gingee Permissions Guide MD HTML.

The routes.json File (Manifest-Based Routing)

For applications that require more powerful and flexible routing, such as RESTful APIs with dynamic path parameters, you can create a routes.json file. When this file is present in an app's box folder, it activates manifest-based routing, which takes precedence over the default file-based routing.

Structure of routes.json

The file must contain a single root object with a routes key, which holds an array of route definition objects.

{
  "routes": [
    {
      "path": "/users",
      "method": "GET",
      "script": "users/list.js"
    },
    {
      "path": "/users/:userId",
      "method": "GET",
      "script": "users/get.js"
    },
    {
      "path": "/users/:userId",
      "method": "PUT",
      "script": "users/update.js"
    },
    {
      "path": "/:category/:slug/images/:imageId?",
      "method": "GET",
      "script": "content/view.js"
    }
  ]
}

Route Definition Properties

Each object in the routes array defines a single endpoint and has the following properties:

Accessing Path Parameters

When a route with dynamic parameters is matched, Gingee automatically parses the values from the URL and makes them available in your server script via the $g.request.params object.

Example: