First Build

After setting up your project, you are ready to build and run. This guide covers the complete developer workflow — from the first build to daily productivity with debugging, testing, and incremental compilation.

Your First Build

On a freshly cloned repository, a single command handles everything:

oidis dev

That's it. The Builder detects a fresh project, resolves dependencies, generates configuration files, runs npm install, compiles TypeScript and SCSS, bundles the frontend, and produces a ready-to-run development build. Subsequent runs of oidis dev are incremental — only changed files are recompiled, making builds significantly faster.

One command to rule them all

oidis dev is the command you will use most often. It is a shortcut for oidis build dev and it takes care of the entire compilation pipeline. On a clean clone it performs the full setup automatically; on an existing project it does an incremental build.

If you need to explicitly install or update dependencies (e.g., after pulling changes that modify package.conf.jsonp), run oidis install separately before building.

Understanding Build Commands

Command	When to use	What it does
oidis dev	Daily — your default command	Incremental dev build with source maps and caching; adds new @Extern / @Resolver / @Route files to ForceCompile
oidis install	After dependency changes	Resolves deps, clones packages, generates configs, runs npm install
oidis rebuild	After config or npm package changes	Full clean rebuild — ignores cache, reinstalls everything
oidis prod	Release preparation	Production build — optimized, minified, no source maps, no dev markers
oidis test	Before commit / CI	Runs all unit tests
oidis test coverage	Quality check	Runs tests with code coverage report
oidis.cmd project-cleanup test:lint	Quick validation	Lint check only — fast, safe, same as pre-commit hook

oidis install deletes the dependencies/ folder

oidis install removes the entire dependencies/ directory and re-clones all Oidis packages from scratch. If you have any uncommitted changes inside dependencies/ — which is common in projects with a separate GUI repository — those changes will be permanently lost.

Before running oidis install:

1. Check if you have any local modifications inside dependencies/ — these are extracted ZIP archives with no version control, so there is no git status to help you. You must manually verify that you have not edited any files there.
2. If you did make changes inside a dependency (e.g., while developing a feature that spans the main project and its GUI package), synchronize those changes back first using IntelliJ's Directory Diff or Beyond Compare — see the Separate GUI Repository workflow for the detailed procedure.
3. Only then run oidis install in the parent project.

Recovery from accidental loss is technically possible via IntelliJ's Local History, but it is tedious and unreliable for large refactors or renamed files. Prevention is the only safe approach.

Development Workflow

Frontend Changes

The most common cycle when working on UI:

1. Edit TypeScript or SCSS files in IntelliJ
2. Build — run oidis dev in the terminal
3. Reload — refresh the browser page

No server restart is needed for frontend-only changes. The browser loads the freshly compiled assets on reload.

Backend Changes

When modifying backend code (models, resolvers, connectors, services):

1. Edit TypeScript files in IntelliJ
2. Build — run oidis dev in the terminal
3. Restart — stop and re-run the application in IntelliJ (the server process needs to pick up the new compiled code)

When to Use oidis install

Run oidis install when:

• You pulled changes that modified package.conf.jsonp or dependency versions
• You added or removed an Oidis dependency (framework package or solution dependency)
• You see path resolution errors in TypeScript (delete tsconfig.json first, then install)
• A colleague reports "works after install" for a change you pulled

You do not need to run oidis install for every build — oidis dev handles incremental compilation on its own.

When to Use oidis rebuild

Run oidis rebuild when:

• You changed npm packages in package.conf.jsonp
• You suspect the incremental cache is stale (rare, but possible after major changes)
• You want to verify a clean build before pushing

oidis rebuild forces a full recompilation without using the cache. It is slower than oidis dev but guarantees a clean state without requiring you to manually delete the dependencies/ folder.

Running the Application

IntelliJ Run Configurations (Recommended)

Most Oidis developers use IntelliJ IDEA's built-in run configurations for day-to-day development. The IDE provides:

• One-click start/stop of the application
• Integrated debugger with breakpoints
• Console output with clickable stack traces

See IDE Configuration for setup instructions.

oidis run — Build + Server

For a combined build-and-run experience:

oidis run                        # build dev + start local server with hot reload
oidis run --run-config=demo      # use a named run configuration
oidis run:demo                   # shortcut for the above

oidis run builds the development release and starts a local server. This is useful for quick verification without setting up IntelliJ run configurations.

Debugging

Oidis provides full debugging support across the entire stack — no console.log guesswork needed.

Source Maps

Dev builds (oidis dev) generate complete source maps for both TypeScript and SCSS. This means:

• Browser DevTools — step through your original .ts files, set breakpoints, inspect variables, view the call stack — all in the source language, not compiled JavaScript
• SCSS debugging — inspect styles in the browser and see the original .scss file and line number, not the compiled CSS
• IntelliJ debugger — attach to the Node.js process and debug backend code with full source map support, breakpoints, watches, and evaluation

LogIt.Debug()

For structured debug logging, use LogIt.Debug() instead of console.log:

LogIt.Debug("Processing batch", { size: items.length, offset: offset });

LogIt.Debug() messages are automatically stripped in production builds, so you can leave them in the code without performance concerns. The LogIt utility also provides Info, Warning, and Error levels for different severity needs.

See Logging for the complete logging API.

Full visibility without console.log

Between source maps (TS + SCSS), the IntelliJ debugger, browser DevTools, and LogIt.Debug(), you have complete visibility into your application at every layer. There is no need for console.log — and the linter will flag it if you try.

Testing

Oidis Builder provides a robust testing infrastructure that supports test-driven development out of the box.

Running Tests

oidis test                                  # run all tests
oidis test unit                             # run unit tests only
oidis test unit path/to/MyTest.spec.ts      # run a single test file
oidis test coverage                         # run tests with coverage report

Single test mode (oidis test unit path/to/MyTest.spec.ts) is invaluable during development — it runs only the specified test file, saving significant time when iterating on a specific piece of logic.

Test Infrastructure

The framework provides specialized test runners for different scenarios:

Runner	Purpose
BaseUnitTestRunner	Standard unit tests — fast, no external dependencies
MongoTestRunner	Tests with in-memory MongoDB — no real database needed
RESTUnitTestRunner	REST API endpoint tests — validates route handlers
Mock server	Configurable HTTP mock for testing external integrations

Tests are fully debuggable in IntelliJ — set breakpoints, step through test code, inspect state — just like production code.

TDD workflow

Write a test → run oidis test unit path/to/MyTest.spec.ts → see it fail → implement → run again → see it pass. The single-file test mode makes this cycle fast and focused.

Verifying Code Quality

The fastest way to check your code before committing:

oidis.cmd project-cleanup test:lint

This runs the same checks as the pre-commit hook:

• TypeScript linting (Oidis ESLint rules)
• SCSS linting (Stylelint rules)
• Copyright header validation
• No console.* calls (use LogIt instead)
• No querySelector usage (use data-oidis-bind instead)
• Naming conventions compliance

Productivity Tips

Oidis is designed as a platform — not just a framework, but a complete set of processes and tools optimized for developer productivity.

• Incremental builds are fast. After the first oidis dev, subsequent builds only recompile changed files. The Builder uses SHA1-based file caching to skip unchanged modules.
• Source maps cover everything. TypeScript and SCSS source maps let you debug in the original language across browser DevTools and IntelliJ. No mental translation from compiled output needed.
• Single test mode saves time. Use oidis test unit path/to/Test.spec.ts instead of running the entire test suite during development.
• IntelliJ is your cockpit. Run configs, debugging, hot reload, code navigation, and refactoring — the IDE is tightly integrated with the Oidis workflow.
• The pre-commit hook catches issues early. Let it run — it validates formatting, copyrights, banned patterns, and lint rules before your code reaches the repository.
• oidis dev is always safe. It never modifies your source files or configuration — it only reads and compiles. You can run it as often as you want.
• Map Builder commands to keyboard shortcuts. In IntelliJ, register Builder commands as External Tools and assign keyboard shortcuts — for example, F5 for oidis dev (matches browser reload), Shift+F5 for oidis rebuild, F6 for oidis test. This eliminates terminal switching and keeps you in flow.

Common Build Issues

TypeScript path resolution errors

Paths in tsconfig.json are auto-generated from the dependency tree. If paths seem wrong:

1. Delete tsconfig.json
2. Run oidis install to regenerate

SCSS compilation failures

SCSS aliases are generated in webpack.config.js. If stylesheets can't find imports:

1. Delete webpack.config.js
2. Run oidis install to regenerate

"Module not found" at runtime

A class might be missing from ForceCompile.ts. Every build (oidis dev, oidis build dev|prod|eap) adds files containing @Extern(, @Resolver( or @Route( to the generated block — oidis install does not touch it. A class without those decorators is never added automatically: import it manually above the generated markers.

Pre-commit hook failures

The hook runs oidis.cmd project-cleanup test:lint. Fix the reported issues (formatting, missing headers, banned patterns) and commit again.

Build Output Structure

build/
├── target/
│   ├── cmd/                  # Startup scripts
│   ├── backend/              # Compiled backend code
│   └── frontend/             # Bundled frontend assets
└── reports/                  # Test results, coverage

---

Next: Dive into the Architecture Overview to understand how Oidis applications are structured.

---

See also: Framework Overview | Builder Overview | Logging | Testing