312 Use

Use use to compose one idea file from another. This matters because Stackpress schemas often start from shared package definitions, and larger projects can split shared enums, props, types, or models into smaller files.

Previously: The previous course, Syntax, explained declarations and nested values. This course focuses on the use declaration, which loads another schema before the current file is interpreted.

312.1. Importing Stackpress Definitions

A scaffolded app starts with the standard Stackpress schema import:

use "stackpress/stackpress.idea"

This package import makes shared Stackpress idea definitions available to the app schema. The important habit is to read it as schema composition, not as a runtime TypeScript import.

312.2. Importing A Local Shared File

Idea also supports relative imports. A project can move shared declarations into a separate file and include them from the main schema.

// shared.idea
enum Role {
  ADMIN "ADMIN"
  USER "USER"
}

type Address {
  street String
  city String
}

// schema.idea
use "./shared.idea"

model User {
  id String @id
  role Role
  address Address
}

When the transformer loads schema.idea, it loads shared.idea and merges the shared declarations into the current schema. That lets the model use Role and Address without redefining them in the same file.

312.3. Extending Imported Models

An imported model or type can be extended locally. This is useful when a base package provides a model and the app needs to add project-specific fields.

use "./User.idea"

model User {
  middleName String? @label("Middle Name")
}

This example adds middleName to the imported User model. The imported schema provides the base shape, while the local file contributes the extra field.

312.4. When To Split Files

Keep one schema.idea while the app is small. A single file is easier for junior developers to scan when the model set is still simple.

Split when shared declarations start making the file harder to maintain. Good candidates are shared enums, reusable types, package imports, and domain areas that are easier to understand as separate files.

312.5. Mistakes To Avoid

use is helpful when it makes the schema easier to read. It becomes harmful when it hides the model shape so thoroughly that a developer cannot tell where a field or enum came from.

312.5.1. Split Too Early

use "./article-fields.idea"
use "./article-display.idea"
use "./article-relations.idea"

model Article {}

This may technically compose schema data, but it makes the main model hard to inspect. If a reader has to open three files to understand one beginner-level model, the split is serving the file system instead of the developer.

312.5.2. Forget That Imports Merge

use "./shared.idea"

model User {
  middleName String?
}

This example extends an imported User model when shared.idea already defines User. If the loaded model looks surprising, inspect the imported definition, duplicate names, and local extension before assuming generation is broken.

312.5.3. Treat use Like Runtime Registration

use "./plugins/app/plugin.ts"

This is the wrong mental model. use composes idea schema files for the transformer; routes, events, database connections, and runtime services still belong in TypeScript plugins and generated output.

Learning checkpoint: Before moving on, make sure you can explain package imports, relative imports, merged declarations, and local extension of imported models or types.

Next course: Continue with Plugins. That course explains idea plugin declarations and how they differ from Stackpress runtime plugins.