Upgrading a project

A project pins Amber in its package.json, with a caret: "@ambers/lang": "^0.31.0". A caret on a 0.x version stops at the next minor release. So npm update never moves a 0.31 project to 0.32. The move is one install, one update, one build, and for 0.32 a short edit of the Gruntfile. Every step on this page was run on a project made by Amber 0.31.5 with amber init.

From 0.31 to 0.32

Install the new Amber and let npm bring the other libraries up to date:

npm install @ambers/lang@^0.32.0
npm update
grunt default devel

grunt default devel recompiles your packages with the new compiler and rebuilds the.js. Run grunt test, start amber serve, and open the page. A 0.31.5 project built, tested and ran this way with no change to its sources.

Then edit Gruntfile.js and package.json, because 0.32 minifies the release build differently. Amber’s kernel is now written in ES2017, and the minifier built into the requirejs optimizer reads only ES5. With the old Gruntfile, grunt deploy still writes the.js, but prints “Cannot uglify file”. The file stays unminified, at about a megabyte for the sample. The fix is what the 0.32 generator writes into a new project:

1. In Gruntfile.js, in the requirejs section, change optimize: "uglify2" to optimize: "none", in deploy and in deploy_lambda.

2. In the same file, make the two deploy tasks run a minify step after the optimizer:

   grunt.registerTask('deploy', ['amdconfig:app', 'requirejs:deploy', 'exec:minify_deploy']);
   grunt.registerTask('deploy:lambda', ['amdconfig:app', 'requirejs:deploy_lambda', 'exec:minify_lambda']);
   

3. Add the two commands to the exec section, next to test_runner:

   minify_deploy: 'npm run minify:deploy',
   minify_lambda: 'npm run minify:lambda'
   

4. In package.json, add the two scripts and install terser:

   "minify:deploy": "terser the.js --compress --mangle --output the.js",
   "minify:lambda": "terser lambda/the.js --compress --mangle --output lambda/the.js"
   

   npm install -D terser
   

After this, grunt deploy ends with the terser step. It writes a the.js of about 550 kilobytes for the sample, the same as a fresh 0.32 project. A project with no backend skips the lambda half.

Two more facts about 0.32. Amber’s tools need Node.js 14 or newer, and the page needs a browser from 2020 or newer. Set "node": ">=14.0.0" in the engines of package.json. A method written with inlineJS: must stay at ES2017 syntax, since the optimizer parses every method it bundles. The changelog lists the rest.

Within 0.31

A 0.31 project takes a newer 0.31 with npm update and grunt devel. Two steps came with the 0.31 line, for projects made by its first releases:

• A project made by 0.31.0 pins Helios at 0.14 and the legacy IDE at 0.11. Before the update, run npm install -D @ambers/helios@^0.15.0 @ambers/contrib-legacy@^0.12.0.
• From 0.31.4 on, Web-JQuery lives in contrib-jquery, under the id amber/jquery/Web-JQuery. A project that imports the old id, amber/web/Web-JQuery, keeps working. contrib-web 0.10.1 and later map the old id to the new one once config.js is regenerated. To use the new id yourself, run npm install @ambers/contrib-web@^0.11.0, change the import in your package, and run grunt. A project with no use for jQuery drops the import, with the code that needs it, and runs npm uninstall @ambers/contrib-jquery. jQuery is then installed only for Helios.

From before 0.31

A project made by Amber 0.25 to 0.30 has the files of one made today, but for a few lines. Bring it to 0.31 first, then follow the section above. The order of the installs matters, because the old pins of one library hold back another:

npm uninstall es6-promise
npm install @ambers/lang@^0.31.0 @ambers/contrib-jquery
npm install @ambers/contrib-web @ambers/domite @ambers/silk
npm install -D @ambers/sdk @ambers/helios
npm install -D @ambers/contrib-legacy

Then two edits. In Gruntfile.js, remove the paths block that named es6-promise and the es6-promise/auto entry in the two mkDefine calls. In index.html, remove the preamble before the require of app that loaded the promise polyfill. Run grunt default devel. Without the Gruntfile edit, grunt devel stops with ENOENT on the file npm just removed.

A project older than 0.25 differs in more than its pins. Make a fresh project with amber init and move your src into it. The project page says which files are yours.