Skip to content

getting-started.md

Latest commit

 

History

History
156 lines (104 loc) · 8.68 KB

getting-started.md

File metadata and controls

156 lines (104 loc) · 8.68 KB
Raw
title Set Up Your Project
sidebar_label Set Up Your Project
description Wire Storm into a project you intend to keep: prerequisites, the four setup routes (fastest with a coding agent), and how to verify the result.

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Set Up Your Project

This page is about getting Storm into a real project: what it needs from your toolchain, which of the four setup routes fits your situation, and how to prove the wiring works before you write application code. If you work with a coding agent, the fastest route is to let it do the wiring: one command gives it everything it needs.

:::tip Just want to see it work? The Quickstart takes about five minutes, with your coding agent or by hand, needs no database server, and ends with a working query and the SQL it generated. It is the fastest way to judge Storm, and it is the recommended first stop. Come back here when you are setting up a project you intend to keep. :::

Prerequisites

Requirement Version
JDK (Kotlin path) 21 or later
JDK (Java path) 21 exactly; preview class files are version-locked
Kotlin (if using Kotlin) 2.0 or later
Build tool Maven 3.9+ or Gradle 8+ (Gradle 8.5+ for the Storm plugin)
Database Any JDBC-compatible database
Node.js (Storm CLI, coding-agent route only) 18 or later

Kotlin users need no preview flags. Java users must enable --enable-preview on compilation, tests, and execution, and must build and run on a JDK 21 toolchain. Installation covers both in full, including the exact Maven and Gradle configuration.

The JDK 21 pin is a property of the platform, not of Storm: the Java API is built on String Templates (JEP 430), a preview feature, and preview class files only load on the JDK that compiled them. When the JDK ships a stable successor, the Java API drops the preview flags and the version pin and stands alongside Kotlin as a first-class path. String Templates covers where that stands today, and which modules are affected (only storm-java21; the core framework and the Kotlin API are not).

Choose a Setup Route

All four routes end at the same place: a project with the Storm dependencies, the metamodel processor, and the Kotlin compiler plugin wired up. With a coding agent, the agent does this for you; the other three routes are the same setup by hand.

Setup with a coding agent (fastest)

If you work with a coding agent (Claude Code, Cursor, GitHub Copilot, Windsurf, or Codex), let it do the wiring. Run one command from the root of your project:

npx @storm-orm/cli init

It installs Storm's rules and skills for your agent, so the agent knows the conventions, the build setup for Gradle and Maven, and the common pitfalls. An existing CLAUDE.md or rules file keeps its content: Storm adds its own marked block. Optionally, it connects a schema-aware MCP server to your development database. That server runs on your machine and is read-only: the agent sees your schema, never your credentials, and sees data only if you allow it.

Then ask the agent for what you need, for example:

  • "Add Storm to this project with the Gradle plugin and the PostgreSQL dialect."
  • "Generate Storm entities for the customer and order tables, and validate them against the schema."
  • "Write a repository method that finds a customer's open orders, and show me the SQL it runs."

Storm entities carry every detail in the model, so the agent has what it needs to act, and it can check its own work: validateSchema() confirms the entities match the database, and SqlCapture shows the SQL a query really runs.

Starting from an empty directory instead? npx @storm-orm/cli demo creates a Kotlin project and has your agent build a small web application on Storm.

See Agentic Coding for the full workflow and Database Connections & MCP for the schema-aware server.

Gradle plugin (recommended for Kotlin)

One plugin application imports the BOM, adds the core dependencies, wires the metamodel processor through KSP, selects the compiler-plugin variant matching your Kotlin version, and sets the Java preview flags.

plugins {
    kotlin("jvm") version "2.4.0"
    id("st.orm") version "@@STORM_VERSION@@"
}

On Kotlin 2.2 and newer the plugin applies KSP itself; on Kotlin 2.0 and 2.1, add id("com.google.devtools.ksp") with the version paired to your Kotlin line. Add the dialect module and JDBC driver for your database, and you are done. See Installation for the plugin's configuration options and the per-Kotlin-version matrix.

Maven BOM

Import the BOM once, then declare Storm modules without version numbers. The metamodel annotation processor is added to the compiler plugin's annotationProcessorPaths, and the Java path needs --enable-preview.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>st.orm</groupId>
            <artifactId>storm-bom</artifactId>
            <version>@@STORM_VERSION@@</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

See Installation for the full pom.xml, including the processor and preview-flag configuration.

Start from a template

Each starter template is a GitHub template repository holding one vertical slice of a working application: two entities with their migration, a repository query, a service, two endpoints, and the tests that cover them. Around three hundred lines, running on H2 the moment it is cloned, with nothing to delete before your own code goes in. Click Use this template, rename the package, and replace the schema:

What each one contains is on the starter templates page. The example projects are a different thing: complete applications on the public IMDB dataset, written to be read and run rather than started from.

Verify the Wiring

Two checks catch almost every setup mistake before it reaches application code.

Does the metamodel generate? After a build, a User entity should have a generated User_ alongside it. If it does not, the annotation processor (Java) or KSP (Kotlin) is not on the compile path. See Metamodel for how generation is configured per build tool.

Do the entities match the database? Schema validation compares every mapped entity against the live schema and reports missing tables, missing columns, type mismatches, and nullability disagreements in one pass. validateSchemaOrThrow() fails loudly; validateSchema() returns the findings as a list so you can assert on them:

dataSource.orm.validateSchemaOrThrow()
ORMTemplate.of(dataSource).validateSchemaOrThrow();

Run it at startup in development, or as a test. Schema Validation covers what is checked, how to scope it to specific entities, and the strict mode.

Next

With a coding agent, keep asking it for what you need: Agentic Coding covers the workflow and how the agent checks its own work. To learn the model yourself, or to review what the agent wrote, work through:

  1. First Entity -- define entities, insert and fetch records
  2. First Query -- filtering, repositories, and streaming
  3. Entities -- annotations, nullability, naming conventions

Integrating with a framework instead? Go straight to Spring Integration or Ktor Integration, which cover dependency injection, transaction management, and configuration for each.

The full map of the documentation, including paths for migrating from JPA and for evaluating Storm in production, is on the introduction page.

Stuck on the setup, or something here did not match what you saw? Ask in Discord or open a discussion.