# Scripts and projects

A `.js` file is enough for a small task. A `.cso` or `.aso` project is an ordinary directory containing related scripts and assets. Both extensions are supported. A project starts `main.js`, or `index.js` if `main.js` is absent.

## Create a project in the app

Choose **Scripts → + → Create project (.aso)**. The dialog accepts `.cso` too. Open the project to edit its entry and add folders or files. Run from a file inside a project saves its drafts and starts the project entry. **Save** writes only the current file.

Scripts live under the device’s resolved ApplesauceOS **Scripts** folder. Use [scriptsDir()](/doc/api/scriptsdir) to find it; do not hard-code a jailbreak prefix. **Import from Files** accepts scripts and folders. Long-press a library item for actions such as rename, duplicate, share and delete.

## Let modules call other modules

```text
Greeting.cso/
  main.js
  actions/
    greeting.js
    format.js
  config.json
```

`main.js`:

```js
const {greet} = require("./actions/greeting");
greet(args.name || "Sam");
```

`actions/greeting.js`:

```js
const {format} = require("./format");
const config = require("../config.json");
exports.greet = function (name) {
  console.log(format(config.prefix, name));
};
```

`actions/format.js`:

```js
exports.format = (prefix, name) => prefix + ", " + name + "!";
```

`config.json`:

```json
{"prefix":"Hello"}
```

Every `./` path belongs to the file doing the import. `../` moves to its parent. Loading a module does not start a separate script; exported functions run when you call them. Modules are cached within each iteration and receive a fresh cache on the next run.

## Files and assets

Use `__dirname + "/result.json"` for data beside the current module. Native file functions do not use CommonJS resolution. Check their documented result: [writeFile](/doc/api/writefile) returns `null` on success and an error string on failure.

[findImage](/doc/api/findimage) resolves a relative template path from the script/project directory. Keep assets in the project so it can move between devices. An image in Photos is not automatically a template file in your project.

## Arguments

Arguments arrive in the reserved, frozen `args` object, also available as `at.args`. Values are strings. A missing key is `undefined`.

```js
const count = Number(args.count || "3");
if (!Number.isInteger(count) || count < 1 || count > 10) {
  throw new Error("count must be an integer from 1 to 10");
}
```

The MCP `start_script` tool accepts `path` and `args`. Keep the returned run ID to inspect or stop that run. Do not use a shared temporary file for arguments.

## JavaScript packages

The loader supports CommonJS `.js`/`.cjs`, JSON, directory indexes, `package.json.main` for imported modules, and nested `node_modules`. It does not automatically install npm packages. Pure JavaScript packages can work if their dependencies use available APIs.

This is not Node.js: built-ins such as `fs`, `http`, `net`, `child_process`, `process`, `Buffer`, native addons and package exports maps are not provided. ES modules must be bundled to CommonJS. Use [file APIs](/doc/api?group=Files%20and%20encoding), [HTTP APIs](/doc/api?group=HTTP%20requests) and [execResult](/doc/api/execresult) where appropriate.

Next: [JavaScript conventions](/doc/javascript) and [reliable automation](/doc/recovery).