# Package structure

Every v2 app follows the same directory convention. This page walks through each directory and file, shows minimal and standard examples, and explains the role of `package.json`.

## Directory reference[​](#directory-reference "Direct link to Directory reference")

| Directory / file                 | Purpose                                                                       | Required? |
| -------------------------------- | ----------------------------------------------------------------------------- | --------- |
| `package.json`                   | Identity (`comindApp`), dependencies, `#typings` import alias                 | Yes       |
| `typings.ts`                     | App-specific TypeScript types via `makeEntity(fields)`                        | Yes       |
| `fields/index.ts`                | Field definitions (`AppField[]`)                                              | Yes       |
| `fields/calc-fields/`            | Calculated/virtual fields (bundled separately for browser)                    | No        |
| `actions/index.ts`               | Action definitions (`AppAction[]`)                                            | Yes       |
| `actions/logic/index.ts`         | Server-side action code (`ActionLogic`)                                       | No        |
| `actions/logic/preconditions.ts` | Precondition checks (`PreconditionLogic`)                                     | No        |
| `views/layouts/default.tsx`      | Form layout (JSX)                                                             | Yes       |
| `views/list-views.ts`            | Grid view definitions (`AppListView[]`)                                       | No        |
| `views/logic/index.ts`           | UI-side hooks (`ViewLogic`)                                                   | No        |
| `settings/index.ts`              | Backlinks, mutations, config (`AppSettings`)                                  | No        |
| `settings/secrets.ts`            | Sensitive config (`COMIND_SECRET_*` vars) - import only from `actions/logic/` | No        |
| `settings/app-mutator.ts`        | Schema post-processing at compile time (install time)                         | No        |

The four required entry points are [fields](/developer-guide/building-blocks/fields-and-field-options.md), [actions](/developer-guide/building-blocks/actions.md), [form layouts](/developer-guide/building-blocks/form-layouts.md), and `typings.ts`. Everything else is optional and added as needed.

## Minimal app example[​](#minimal-app-example "Direct link to Minimal app example")

The simplest possible app - `app-table-row` - contains only the required files:

```
app-table-row/
├── package.json
├── typings.ts
├── fields/index.ts
├── actions/index.ts
└── views/layouts/
    ├── index.ts
    └── default.tsx
```

Start here when scaffolding a new app. Add optional directories only when you need server-side logic, calculated fields, or custom settings.

## Standard app example[​](#standard-app-example "Direct link to Standard app example")

A production app like `app-task` uses most of the available directories:

```
app-task/
├── package.json
├── typings.ts
├── fields/
│   ├── index.ts              # Re-exports all field modules as AppField[]
│   ├── fields-core.ts        # Core fields (title, description, state)
│   ├── fields-dates.ts       # Date fields
│   ├── fields-people.ts      # People/assignee fields
│   ├── ...
│   └── calc-fields/index.ts  # Calculated fields (bundled for browser)
├── actions/
│   ├── index.ts              # AppAction[] definitions
│   └── logic/
│       ├── index.ts          # ActionLogic (server-side code)
│       └── preconditions.ts  # PreconditionLogic
├── views/
│   ├── layouts/
│   │   ├── index.ts          # AppLayout map
│   │   └── default.tsx       # Main form layout (JSX)
│   └── logic/index.ts        # ViewLogic (UI-side hooks)
└── settings/
    ├── index.ts              # AppSettings (backlinks, mutations)
    ├── app-mutator.ts        # Schema post-processing
    └── secrets.ts            # Sensitive config
```

Notice how `fields/index.ts` re-exports from smaller modules (`fields-core.ts`, `fields-dates.ts`, etc.). This keeps individual files short while the engine still receives a single `AppField[]` array. The same pattern applies to actions - `actions/index.ts` exports one `AppAction[]`, but the definitions can be split across multiple files.

The `calc-fields/` directory holds calculated fields that run in the browser. The build system bundles them separately so they can execute on the client without pulling in server-only code.

For details on the [settings model](/developer-guide/building-blocks/settings-model.md) - including backlinks, mutations, and secrets - see the dedicated page.

## The `package.json` file[​](#the-packagejson-file "Direct link to the-packagejson-file")

Every app's `package.json` includes a `comindApp` block that the engine reads at startup:

```
{
  "name": "@comind/app-task",
  "version": "0.5.161101",
  "comindApp": {
    "icon": "check",
    "publishingAlias": "TASK",
    "titleSingular": "Task",
    "titlePlural": "Tasks"
  },
  "dependencies": {
    "@comind/api": "*",
    "@comind/plugin-color": "*",
    "@comind/plugin-notification": "*"
  },
  "imports": {
    "#typings": "./typings.ts"
  }
}
```

Key fields inside `comindApp`:

* `publishingAlias` - the short code used in URLs and API calls (e.g. `TASK`, `TICKET`)
* `titleSingular` / `titlePlural` - display names shown in the UI
* `icon` - the icon identifier rendered next to the app name
* `inheritFrom` - points to a parent app when building a child app (see below)

The `imports` field defines the `#typings` alias so that app code can import types with `import { entity } from '#typings'` instead of relative paths. This alias is required.

Dependencies follow the standard npm format. List `@comind/api` for access to the core API, and add any [plugins](/developer-guide/building-blocks/plugins-and-inheritfrom.md) the app needs.

## Child apps and `inheritFrom`[​](#child-apps-and-inheritfrom "Direct link to child-apps-and-inheritfrom")

A child app extends a parent by adding `inheritFrom` to `comindApp` and listing the parent as a dependency:

```
{
  "name": "@customer/app-custom-task",
  "version": "0.5.241101",
  "comindApp": {
    "icon": "check",
    "publishingAlias": "TASK",
    "titleSingular": "Task",
    "titlePlural": "Tasks",
    "inheritFrom": "@comind/app-task"
  },
  "dependencies": {
    "@comind/api": "*",
    "@comind/app-task": "*"
  },
  "imports": {
    "#typings": "./typings.ts"
  }
}
```

The child inherits all fields, actions, layouts, and settings from the parent. It can then override or extend any of them. This is the primary mechanism for customer-specific customization. See [Plugins and inheritFrom](/developer-guide/building-blocks/plugins-and-inheritfrom.md) for the full inheritance model.