Skip to content

Projects

Starting a project: nomi new and nomi init

Section titled “Starting a project: nomi new and nomi init”

nomi new <module path> [dir] starts a module in dir (a new directory named for the path’s last element when left out). It writes a nomi.toml whose name is that element without a /vN suffix, written as an identifier (hello-world is hello_world), with entry_points = ["main"], a go.mod with the module line and the go line of the Go release nomi pins, a main.nomi that prints hello, and an AGENTS.md for coding agents that names the commands and links the cheat sheet, keeping a main.nomi or AGENTS.md already there. It refuses a directory with a go.mod or a nomi.toml, naming nomi init. It prints what it wrote and the next command.

nomi init [module path] makes the current directory a module. It writes the nomi.toml and the go.mod it lacks, as nomi new writes them, and never replaces either. The module path is the go.mod’s when there is one (a different argument is refused), and the argument otherwise, which is then required. entry_points lists the module-relative name of every file under the directory with a top-level fn main (tools, test files, hidden directories and directories with their own nomi.toml are skipped), or ["main"] when there is none and there are no tools. It writes no source file, refuses a directory that holds both files, and prints what it wrote.

A Nomi module’s identity lives in two files at the module root:

  • go.mod: the Go module path (used by go tooling and the module proxy), dependency graph (require / replace), and Go version. Standard go.mod syntax; nothing Nomi-specific. nomi writes it (nomi new, nomi init, nomi add, nomi remove, nomi update, nomi fetch), and a Nomi project commits it and go.sum without editing either.
  • nomi.toml: the Nomi-side identity ([module].name, the module’s short name used by other modules’ import paths) and the entry points other than the module’s tools ([module].entry_points; every file under tools/ is an entry point without being listed, Project mode).
# nomi.toml
[module]
name = "my_app"
entry_points = ["main"]
# go.mod
module github.com/example/my_app

go 1.27.0

require example.com/shared_kit v0.0.0
replace example.com/shared_kit => ../shared_kit

Every key nomi.toml accepts:

TableKeyWhat it holds
[module]nameThe module’s short name, the first part of other modules’ import paths.
[module]entry_pointsThe files with a fn main, other than tools (Project mode).
[i18n]localesThe locales every phrase is translated into, and whose CLDR data the program carries ([i18n]).
[i18n]partial_localesLocales whose catalogs may leave a phrase out.
[i18n]source_localeThe language of phrase declarations’ own text; en when left out.
[i18n]catalogsThe catalog directory under the module root; locales when left out.
[i18n]web_embeddedThe locales a browser build puts in app.wasm (Locales in the browser).
[money]custom_currenciesThe custom currencies the module’s literals may write ([money]).

The two files are siblings; neither subsumes the other. Cross-module dependencies are Go’s require directives: a required module whose root holds a nomi.toml is importable under its [module].name (spec §14). A replace that points a requirement at a local directory makes that directory the module, as in Go; nomi add ../shared_kit writes both lines above.

A Nomi module is a directory containing both go.mod and nomi.toml, and it is the project root of every file under it. nomi.toml’s entry_points lists the files that contain fn main, other than the module’s tools. Every .nomi file under the module’s tools/ directory is a tool, which nomi tool <module> <name> runs, and an entry point without being listed. Test files there are not tools, and neither is a file in an internal/ directory there, which is where a tool’s helpers go. Listing a tool in entry_points is allowed and changes nothing.

my_project/
  go.mod             # Go-side identity and dependencies (require, replace)
  nomi.toml          # Nomi-side identity and entry points
  main.nomi          # an entry: fn main and an optional fn boot
  tools/
    seed.nomi        # a tool, an entry run by nomi tool my_app seed
  math.nomi          # library file (no fn main)
  models/
    user.nomi
  internal/
    impl.nomi        # reachable from anywhere in this module; blocked cross-module
cd my_project
nomi run main.nomi        # runs the entry main.nomi
nomi tool my_app seed     # runs tools/seed.nomi

Every entry point, each file listed in entry_points and each tool, must have exactly one fn main, and every other file must have none. A file inside internal/ is reachable only from files under the parent of that internal/, and from no other module, whether or not it is pub. See the Module boundaries note in spec §14.

File mode and project mode differ only in where the project root comes from: the file’s own location, or nomi.toml’s.

A command or the editor finds the project root of a file, such as one deep in a subdirectory, by walking upward from it:

  1. First directory containing nomi.toml → project root (project mode).
  2. Else first directory containing main.nomi → project root (file mode).
  3. Else the file’s own directory → fallback for true single-file scripts.

An extensionless #! script’s walk stops at its own directory (Extensionless scripts in Scripts), in the editor as on the command line.

The walk stops at any workspace bound the host has supplied (the editor’s open folder, for instance); it never escapes above. nomi run, nomi test, nomi check, the language server and other tooling share this one rule, so a file opened in an editor resolves its imports to the same files nomi run loads.

So a file in a subdirectory, such as app/prod.nomi, imports types.nomi one directory up: the walk ends at the directory that holds main.nomi or nomi.toml, not at the file’s own.

nomi.toml’s [i18n] table names the locales whose CLDR data the program carries (A program’s locale data) and how its phrases are translated (spec §18 Phrases):

# nomi.toml
[i18n]
source_locale = "en"
locales = ["en", "pl", "pt", "pt-PT"]
partial_locales = ["de"]
catalogs = "locales"

Each entry is a BCP 47 tag, read as Locale.parse reads one and kept in its canonical spelling ("PL" is pl), in the order written, which is the order Locale.available() returns. A program with no [i18n] table carries every locale. Each of these is an error at the manifest, which nomi check, nomi run and the editor report: an empty list, an entry that is not a tag ("pt_BR", whose error suggests pt-BR), one listed twice after canonicalization, und (CLDR’s root, which every program carries), and a tag for which neither CLDR nor any parent of it but root has data (qaa).

source_locale is the locale a phrase declaration’s own text is in, English when it is left out. partial_locales are locales whose catalogs may leave a phrase out, which then shows in the source locale; they need locales, are checked as its entries are, may not repeat one, and the program carries their data too. catalogs is the directory under the module root holding a directory of catalogs per locale, locales when it is left out; it must stay under the root. web_embedded are the locales a browser build compiles into app.wasm (Locales in the browser), the source locale when it is left out; it needs locales, and each entry must be one locales or partial_locales lists.

The program carries the data of one pinned CLDR release, 48.2. Each translation is an entry in a catalog: a TOML file at the declaring file’s path under the catalog directory, in a directory per locale, so shop/cart.nomi’s Polish catalog is locales/pl/shop/cart.toml. Each locale in locales must have every phrase, and a locale in partial_locales may leave any out. What a catalog holds is in std::phrase.

nomi phrases accept <locale> <phrase> marks a locale’s translation of a phrase current: it records the phrase’s text as it is now as the source the translation was made from. <phrase> is the name of a phrase declaration, or path/to/file:name when two files of the module declare one of that name.

nomi.toml’s [money] table lists the custom currencies (std::currency) the module’s source may write as a literal:

# nomi.toml
[money]
custom_currencies = ["PTS:0", "BTC:8"]

Each entry is a custom currency as its literal writes it, the code, a colon and the minor digits, and must be one Currency.custom accepts. Each of these is an error at the manifest: an entry with no digits ("PTS"), a malformed code ("pts:0"), an ISO 4217 code ("EUR:2"), digits that are not a whole number from 0 to 18 written without leading zeros ("PTS:19", "PTS:00"), and an entry listed twice. A module with no [money] table, or an empty list, writes no custom currency literal. The table is the module’s own: a dependency’s literals belong to the dependency’s nomi.toml, and the application’s list does not reach them.