Install Amber and make your first project

This page takes you from nothing to a running Amber project with Helios open on it. The commands are the same on Linux, macOS and Windows. The example project is called Hello Amber, and every detail below comes from that project.

Install Node.js

Amber’s tools run on Node.js 14 or newer. Download it from https://nodejs.org, or install it with your system’s package manager. The installer brings npm with it. Check both:

node -v
npm -v

Install the amber command

npm install -g grunt-cli grunt-init @ambers/cli

This installs three tools. The @ambers/cli package is the amber command and the amberc compiler. grunt-init generates a project, and amber init drives it. grunt-cli runs the build of a project, which is a Gruntfile.

On Linux and macOS, npm installs global packages into a system directory by default, and asks for sudo. You can give npm a directory of your own instead. Run this once, before the install above, and add the second line to your shell’s profile too:

npm config set prefix=~/npm
export PATH="$PATH:$HOME/npm/bin"

Run amber with no arguments to check the install. The first line names the version of the amber command, the version of Amber it carries, and your Node.js. Then it lists the six commands it knows: config, help, init, repl, serve and version.

Make a project

Make an empty directory and run amber init in it:

mkdir helloamber
cd helloamber
amber init

The directory must be empty. amber init stops when it finds a file there.

amber init asks thirteen questions. Each shows a default in parentheses, and Enter accepts it. The first three shape your project:

1. Project title. A name for people to read. Type Hello Amber.
2. Main class and package of Amber application. The generator derives HelloAmber from the title. This is the class that starts your application and the package that holds it. In lowercase, helloamber, it is the name of the project in package.json.
3. Namespace of the new Amber package. The default is amber-helloamber. Your packages are loaded under this name, and local.amd.json maps it to the src directory.

The rest are a description, your name and email, the version 0.1.0, the repository, homepage and issue tracker, your URL, and the license, MIT by default. grunt-init reads your name and email from git, and guesses GitHub URLs from your git user name. The last question asks whether you want to change an answer. Press Enter for no.

Node.js 24 prints a warning about padLevels while the questions run. It comes from an old library inside grunt-init and changes nothing.

Then amber init writes the files and runs two commands for you. npm install fetches Amber and the libraries into node_modules. grunt default devel compiles the Smalltalk sources and builds the.js, the one script the page loads. This takes a minute or two. It ends with “The project should now be set up.”

What is in the project

The project is ready for git init.

Start the server

amber serve

amber serve serves the project directory at http://localhost:4000/, and it writes the files that Helios commits. Leave it running. Ctrl+C stops it. amber serve --port 4001 uses another port.

Open the page

Open http://localhost:4000/ in your browser. The sample page has six buttons. Click “Hello from Silk » TAG:”, and a line appears in the list under the buttons.

As soon as Amber has loaded, a small dialog appears with two buttons, “legacy IDE” and “Helios IDE”. Esc closes it. Press Shift, Shift, Ctrl, Shift to bring it back.

Click “Helios IDE”. Helios opens in a new window. Browsers block that window the first time. Allow popups for localhost in the address bar, and click the button again.

The legacy IDE opens inside the page itself, with a Transcript, a Workspace, a test runner and a class browser in tabs. It is older and smaller than Helios, and it needs no popup.

Your first change in Helios

Helios opens with a Browser tab in front and a Workspace tab beside it. The browser has four columns: packages, classes, protocols and methods. Select the package HelloAmber in the first column and the class HelloAmber in the second. The third column starts on -- all --, so the fourth lists every method of the class. Select doSilkTAG there. Its source appears below the columns.

The method is one line: '#output-list' asSilk LI: 'Silk TAG: added me!'. Read it as Smalltalk reads it. A message with no argument, such as asSilk, goes first. The string '#output-list' receives it and answers the element with that id, wrapped for Silk. A message with a keyword and an argument, such as LI:, goes last. The element receives it and appends a list item with the text. Between the two sit the operators, as in 3 + 4. Messages of one kind go left to right, and parentheses change the order where you need it.

Change the string 'Silk TAG: added me!' to 'Hello from Helios!' and press Ctrl+S. Helios compiles the method into the running page. Click the Silk button on the page: the new text appears in the list. Nothing is on disk yet.

To write the change to disk, commit the package. Press Ctrl+Space to open the Action menu, then k for Commit package. Helios sends the package to amber serve, which writes src/HelloAmber.st and src/HelloAmber.js, and it shows “Commit successful”. Reload the page. It loads the committed code, and the Silk button still says Hello from Helios.

That is the loop. Save to try, commit to keep.