Library CLI
Five commands that create, install, sync, check and remove the shared libraries in
libs/. Use a library for domain, utility, UI or platform code that several apps import.Words Used on This Page
TermDescription
library
A folder under
libs/ holding code several apps share: domain modules, UI or utilities.template
A ready-made library from Akan.js, such as
shared or util, that install-library copies in.akan.source
The stamp
install-library puts in the library's package.json: origin, commit or version, hash.drift
An installed library whose files no longer match the hash in its stamp.
What Each Command Touches
Command
libs/<lib>Root
package.jsonGit history
Add a library
create-library
✓
Start a new library you fill in yourself.
install-library
✓
✓
✓
Copy in a template such as
shared or util.Keep it current
sync-library
✓
Refresh the generated files after you change the library.
library-status
Check whether installed libraries changed after the install.
Remove
remove-library
✓
Delete the whole library folder.
✓ChangedUntouched
Common Rules
- Name the library, or pick it from a list.
remove-libraryandsync-librarylist the libraries inlibs/when the name is missing or unknown;create-libraryandinstall-libraryask you to type one when it is left out. akan sync <lib>is the same step assync-library.create-libraryruns it for you, andakan lint <lib>runs it before linting.- Only an installed library has a stamp. A library made with
create-libraryshows asunstampedinlibrary-status.
Commit your own work before these.
install-library stages the whole working tree with git add . and commits it, and remove-library deletes the folder without asking.Related Pages
create-library
Create a new shared library in
libs/<lib-name>/ for code several apps reuse.
It starts with the standard folders and one empty service module, then runs sync-library.Signature
Arguments
lib-nameStringrequired
Library name. It is lowercased and spaces become
-; asked for if left out.Notes
NameDescription
what it creates
Config files, plus the
env/, lib/, common/, srvkit/, webkit/ and ui/ folders.sample module
lib/_<lib-name>/ is an empty service module: dictionary, service, signal and store.one word
Use one lowercase word. A hyphen lands in the sample module's class names and breaks them.
importing
Apps import it as
@libs/<lib-name>/client or @libs/<lib-name>/server; no config to add.Examples
remove-library
Remove a library from the workspace by deleting its whole
libs/<lib>/ folder, without asking.
Use it when no app should import the library, sync it or depend on it anymore.Signature
Arguments
libString
A library in
libs/, such as util. Leave it out, or mistype it, to pick one from a list.Notes
NameDescription
what stays
Apps'
@libs/<lib> imports stay, and so do the packages merged into the root package.json.afterwards
Delete those imports, then run
akan sync <app> for each app that used the library.Examples
sync-library
Regenerate one library's generated files and refresh its dependency list.
Run it after you add or rename files, change packages, or edit the library's config.
Signature
Arguments
libString
A library in
libs/, such as util. Leave it out, or mistype it, to pick one from a list.Notes
NameDescription
generated files
client.ts, server.ts, every index.ts, the lib/ barrels and akan.lib.json; never edit them.packages
Each package the library imports is written into its
package.json at the root version.used libraries
The libraries it imports get their generated files refreshed too.
Examples
install-library
Install a ready-made library template such as
shared or util into libs/<lib-name>/.
You can run it again: the copy overwrites the library source and leaves your testing env alone.Signature
Arguments
lib-nameStringrequired
Template name, such as
shared or util; asked for if left out.Notes
NameDescription
source
The installed
akanjs package when it ships the library; otherwise the Akan.js GitHub repository.testing env
env/env.server.testing.ts is copied from env.server.example.ts only when it is missing.stamp
Writes the
akan.source stamp that library-status compares against.packages
Merges its packages into the root
package.json, newer version wins, then runs bun install.git commits
Commits the copy if anything changed, then the merge; each runs
git add . on the whole tree.shared
shared imports util, so install util first, as create-workspace --libs true does.Examples
library-status
Report whether each library still matches the source it was installed from.
It checks every library in
libs/ and marks each one clean, drifted or unstamped.Signature
Options
--formatStringdefault texttext | json · -f
text is a list for a person to read; json is an array with each library's stamp and hash.Notes
NameDescription
clean
The library's files hash to the value in its
akan.source stamp.drifted
A file changed since the library was installed.
unstamped
There is no stamp, as with a library made by
create-library.compared files
Every file in
libs/<lib>/, committed or not, except gitignored files and env/.akan.source
Holds
origin, sha (commit or package version), hash and syncedAt.exit code
It only reports: the command succeeds even when a library drifted.
Examples