Table of Contents

Modules and packages

Modules and packages both contain ordinary JavaScript or TypeScript modules, but they differ in ownership, loading, and security.

Module Package
Best for Your own scripts for one server Versioned features that can be installed or shared
Location Documents/smudgy/<server>/modules/ Documents/smudgy/<server>/packages/<name>/
Entry point Every top-level file loads One manifest-selected entry module loads
Configuration Code or your own files Install-time parameters through smudgy:params
Dependencies Direct imports Declared and version-resolved by the manifest
Security Unrestricted user code Sandboxed unless explicitly trusted

Modules

A module belongs to you and runs with full access to the scripting runtime. Top-level files load automatically; subdirectories can hold helpers imported by those files.

Use modules for personal aliases, triggers, mapper glue, and experiments. Because modules are unrestricted, do not copy in code you have not reviewed.

Packages

A package is a folder containing smudgy.package.json and an entry module, index.ts by default. The packages window creates and manages these folders. Packages can be enabled, versioned, published, and installed with their dependencies.

A local package detail showing its source files, manifest summary, sandbox status, and publish action

Packages run in separate sandboxes by default. The manifest declares both the smudgy features and the Deno resources the package needs; smudgy shows those permissions before the package runs. See Permissions, sandboxing, and trust.

Import installed packages

Published packages use addresses such as smudgy://kapusniak/arctic-prompt. Importing that address loads the package's entry module; adding a subpath imports a file inside it.

Shared state and events use virtual modules instead of importing the producer's code: 

import { send } from "smudgy:core";
import { prompt } from "smudgy:events/kapusniak/arctic-prompt";
 
prompt.on(({ hp }) => {
  if (hp < 100) send("quaff healing");
});

A package that imports another package's code lists it under dependencies. A package that only consumes its shared state, events, or procedures can list it under requires. User modules do not have manifests, but the packages they consume must still be installed.

See Package manifests and publishing for dependency syntax.