Your first program
This page writes a program, runs it, compiles it to a native binary, and then
breaks it on purpose to show what the compiler says when something is wrong.
It assumes nish and LLVM are installed as described in
Installation.
Hello, world
Make an empty directory and save this as hello.ts inside it:
export const main = (): i32 => {
console.log("hello from Nish");
return 0;
};
A Nish program starts at main, which is exported from the file you compile.
It takes no parameters. Its return value is the program's exit status, so
return 0 means success. i32 is a 32-bit integer: Nish writes the width of
a number in its type, and Coming from TypeScript
explains why. A main with nothing to report can return void instead, and
then exits with 0. The rules for main are in the reference's
main section.
Without main
A short program can leave main out and write its statements at the top
level, the way a script does:
const square = (n: i32): i32 => n * n
const sides = [3, 4, 5]
for (const side of sides) {
console.log(square(side))
}
The compiler gathers the statements into a main that returns void, so the
binary is the same one you would get by writing main yourself, and it exits
with 0 unless the code calls process.exit. Two rules keep the file meaning
the same thing natively and under Node, where the statements run where they
stand:
- Declare each function above the first statement that uses it.
-
A function cannot read a variable of the top-level code. Pass it the value
as a parameter, or make it an annotated constant above the code, such as
const LIMIT: i32 = 4.
This one breaks the second rule, and the compiler says which variable and why:
let count = 0
const bump = (): void => {
count += 1
}
bump()
Only the file you compile may do this, and only when it declares no main.
The details are in the reference's
Top-level code section.
Run it
nish run hello.ts
hello from Nish
nish run compiles the file, links it, and starts it. Anything after the file
name is passed to the program as its arguments, which it reads from
process.argv. The binary is cached, so running an unchanged file again
skips the link.
Compile it to a native binary
nish hello.ts --link hello
./hello
wrote hello.ll
linked hello: 4712 bytes (speed)
hello from Nish
The first two lines come from nish. It wrote hello.ll, the LLVM IR for the
program, then linked an executable named hello beside it. The byte count
depends on your platform and version, and speed is the default build
profile; the CLI page has the others. The last line is ./hello running. The binary needs
nothing installed beside the system's C library: no Node, no runtime and no
garbage collector.
Without --link, nish hello.ts -o hello.ll stops after writing the IR and
needs no clang.
When it does not compile
Save this as greet.ts. It has a mistake on line 8: "3" is a string where
greet takes a number.
const greet = (name: string, times: i32): void => {
for (let i = 0; i < times; i++) {
console.log(`hello, ${name}`);
}
};
export const main = (): i32 => {
greet("Nish", "3");
return 0;
};
nish run greet.ts
greet.ts:8:17: error: Argument 2 of `greet`: expected i32, got string
8 | greet("Nish", "3");
| ^~~
An error names the file, the line and the column (greet.ts:8:17), says what
is wrong, and underlines the place; on a terminal the label is red and the
underlined code is picked out in colour
(when colour is used).
Nothing runs, and nish exits with 1.
When a file has several errors, the compiler reports them in the order they
appear in the file.
Every error also has a code, a stable name for the rule that was broken.
Add --json to see it. With nish run, flags go before the file name:
nish run --json greet.ts
{"file":"greet.ts","line":8,"column":17,"endLine":8,"endColumn":20,"severity":"error","code":"NL2117","message":"Argument 2 of `greet`: expected i32, got string"}
The code here is NL2117. A message's wording can change between releases,
but a code always means the same rule, so search for the code, and key editors
and scripts on it. The first digit says which stage of the compiler refused the program: NL1… for
syntax Nish forbids outright, NL2… for the type checker, NL3… for modules
and packages. The reference's
Rejected by the checker and
Forbidden constructs
sections list the rules.
Change "3" to 3, and nish run greet.ts prints hello, Nish three times.
Fixes the compiler can make for you
Some errors have only one sensible repair, and the compiler can apply it
itself. Save this as check.ts:
export const main = (): i32 => {
const xs = [1, 2, 3];
if (xs.length) {
console.log("non-empty");
}
return 0;
};
Nish has no truthiness, so if (xs.length) is an error: a condition has to
be a boolean. Ask for the fix:
nish --fix check.ts
fixed check.ts (1 edit)
The file now reads if (xs.length !== 0), and nish run check.ts prints
non-empty. --fix rewrites the file in place without a backup, so use it on
files you have saved or committed. Anything it could not repair is then
reported as usual.
Exit codes
nish uses its exit status to say what happened:
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | the program was rejected: a compile error, or an input file that does not exist |
| 2 | the command line was wrong: an unknown flag, a missing argument, no input file |
| 3 | the C toolchain is missing or failed: --link found no clang, or the link step failed |
| 70 | an internal compiler error. This is a bug in nish, not in your program; please report it with the file and the command line |
nish run answers with these codes until your program starts. After that, the
exit status is your program's own: whatever main returns.
A program can also stop with a panic. A panic is how Nish ends a program
that reached a state it cannot continue from, such as reading past the end of
an array, or arithmetic that overflows. Integer arithmetic is checked, so this
program, saved as overflow.ts, stops rather than wrap round to a negative
number:
export const main = (): i32 => {
let n: i32 = 2147483600;
for (let i = 0; i < 100; i++) {
n = n + 1;
}
console.log(`${n}`);
return 0;
};
nish run overflow.ts
attempt to add with overflow
The message goes to stderr, and the program exits with 1. A program can also
panic deliberately by calling panic("message"). A failure the caller is
expected to handle is reported with a Result instead; see
Errors and Result.
Where next
- Coming from TypeScript: what carries over, what Nish refuses, and what to write instead.
-
The command-line interface: every flag
nishtakes.

