Libraries

Amber’s libraries are npm packages. A project takes one in with npm install and regenerates its loader configuration. Then it names the library’s package in the imports of its own package. A plain JavaScript library from npm comes in the same way, with one small file more. And your own project is a library already, as the project page says. This page shows all three on the Hello Amber project.

Amber’s libraries

The libraries of the Amber project live in the @ambers scope on npm. npm search @ambers lists them. These are the ones a project uses:

The scope also holds @ambers/prof-stef, the Smalltalk tutorial. Outside it there is mini-mvp, presenters for Silk and for Web. A presenter keeps a frame of the page in step with a block. A library you publish is found the same way. amber init puts the keywords Amber and Smalltalk into every project’s package.json, and npm search amber smalltalk lists whatever carries them.

Taking an Amber library in

The sample project already has Silk. This is what it took, and what any other Amber library takes.

Install it, so that it is in node_modules and in package.json:

npm install @ambers/silk --save
grunt devel

grunt devel regenerates config.js. The library’s local.amd.json maps its namespace, silk, to its src. That mapping is now in the configuration, so the loader can find silk/Silk.

Then name the package in the imports of your package. In Helios, select the package HelloAmber in the browser. The source pane shows its definition:

Package
	named: 'HelloAmber'
	imports: {'amber/jquery/Web-JQuery'. 'amber/web/Web'. 'silk/Silk'}
	transport: (AmdPackageTransport namespace: 'amber-helloamber')

Add 'silk/Silk' to the list and press Ctrl+S. Commit the package with Ctrl+Space, k, and reload the page. From then on, Silk loads before your package, and your methods can send asSilk and build elements.

Two more lines keep the build in step. In Gruntfile.js, add 'silk/Silk' to the libraries of the amberc section. The compiler then knows Silk’s classes when it compiles your sources from the command line. The deploy bundle needs nothing. The optimizer follows the imports, and the sample’s the.js carries Silk, Web and jQuery, which deploy.js never mentions.

A package only the tests use is added to testing.js instead, and amber/core/SUnit is already there.

Taking a JavaScript library in

A JavaScript library from npm knows nothing of Amber, so the project tells the loader where its file is. The example is dayjs, a small date library. Install it:

npm install dayjs --save

The package puts its browser build at node_modules/dayjs/dayjs.min.js. Make a file dayjs.amd.json in the root of your project:

{
  "paths": {
    "dayjs": "dayjs.min"
  }
}

The file is named after the package’s directory under node_modules. Its paths are relative to that directory. grunt devel picks it up, and config.js now maps dayjs to node_modules/dayjs/dayjs.min. An Amber library brings such a file along; for a plain one, you write it.

Then import the module into your package, bound to a name:

Package
	named: 'HelloAmber'
	imports: {'amber/jquery/Web-JQuery'. 'amber/web/Web'. 'silk/Silk'. 'dayjs' -> 'dayjs'}
	transport: (AmdPackageTransport namespace: 'amber-helloamber')

The association binds what the module exports to the variable dayjs. The variable is visible in every method of the package. Press Ctrl+S, commit, and reload the page. The module is bound when the package loads. A method that uses it before the reload stops with “dayjs is not defined”.

dayjs exports a function. A function is a block in Amber, so value calls it, and format: goes to what the call answers. This method, saved into HelloAmber, answers the date:

today
	^ dayjs value format: 'YYYY-MM-DD'

HelloAmber new today printed '2026-10-31' on the day this page was written. The JavaScript page says how the rest of the call works. The compiler accepts dayjs because the import names it, so grunt compiles the package as before. grunt deploy puts dayjs.min.js into the bundle.

The library’s file must be a module the loader understands: an AMD module, or a UMD build. Most libraries ship one. A file that only sets a global needs a shim entry in the same .amd.json. The .amd.json files of @ambers/helios show the form.

Making your project a library

Your project is a library already. Its src, its local.amd.json and its package.json are all another project needs. To publish it:

1. Choose the name in package.json. The namespace in local.amd.json stays, since every user of the library names its packages by it.
2. Make @ambers/lang a dependency with a lower bound, ">=0.32.0", not a caret. A library runs on any later Amber, and a caret would stop at the next minor release.
3. Keep the keywords Amber and Smalltalk, so that npm search finds it.
4. Run npm publish. npm leaves out what .gitignore names, so config.js and the.js stay home.

A project that uses your library runs npm install yourlibrary --save and grunt devel. It adds yournamespace/YourPackage to the imports of its package, commits and reloads. The README that amber init wrote says this in the library’s own words.