# YepCode JavaScript Code Rules

> This file provides guidelines for LLMs to write JavaScript code compatible with the YepCode platform and ready to use it's specific helpers.

This file provides guidelines for LLMs to write JavaScript code compatible with YepCode platform and ready to use its specific helpers.

[Download this file](/docs/ai-rules/code/javascript.md)

## JavaScript Code Rules

[Section titled “JavaScript Code Rules”](#javascript-code-rules)

## Quick Reference

[Section titled “Quick Reference”](#quick-reference)

| Aspect                  | Guideline                          |
| ----------------------- | ---------------------------------- |
| **Runtime**             | Node.js v22                        |
| **Main file (process)** | `index.js`                         |
| **Entry point**         | `async function main()`            |
| **Export (required)**   | `module.exports = { main }`        |
| **Parameters**          | `yepcode.context.parameters`       |
| **Variables**           | `process.env.X` or `yepcode.env.X` |
| **Modules**             | `yepcode.import("module-slug")`    |

### Critical Rules

[Section titled “Critical Rules”](#critical-rules)

* ✅ **Always** export `main` with `module.exports = { main }`
* ❌ **Never** call `main()` directly
* ✅ **Always** use `async/await` for async operations
* ✅ **Always** add `try/catch` around the main flow for actionable errors
* ❌ **Never** use dynamic module names with `yepcode.import()`—module names must be **hardcoded strings** (e.g. `yepcode.import("module-name")`), not variables
* ✅ Use **const** or **let**; avoid **var**

## Process Template

[Section titled “Process Template”](#process-template)

```javascript
async function main() {
  // Access input parameters
  const { parameters } = yepcode.context;


  // Your code here


  // Return result
  return { message: "Success!" };
}


module.exports = { main };
```

## Helpers Usage

[Section titled “Helpers Usage”](#helpers-usage)

* Access execution info: `const { id, comment } = yepcode.execution;`
* Access process info: `const { id: processId, name: processName } = yepcode.execution.process;`
* Access schedule info (if present): `const { id: scheduleId, comment: scheduleComment } = yepcode.execution.schedule;`
* Access team timezone: `const timezone = yepcode.execution.timezone;`
* Use environment variables: `const apiKey = process.env.API_KEY; // or yepcode.env.API_KEY`
* Import YepCode modules: `const { myFunc } = yepcode.import("module-name");`
  * Caution: module names must be **hardcoded strings** (no variables)
* Import with version: `const { myFunc } = yepcode.import("module-name", "v1.0");`
* Run another process: `await yepcode.processes.run("process-identifier", options);`

## Logging

[Section titled “Logging”](#logging)

```javascript
console.log("INFO message");
console.debug("DEBUG message");
console.info("INFO message");
console.warn("WARNING message");
console.error("ERROR message");
```

## Dependencies Management

[Section titled “Dependencies Management”](#dependencies-management)

* You may use external npm packages
* Just add the require statement to the code and the package will be installed automatically
* If package import name is different than the package name, you must use the `@add-package` comment:

```javascript
// @add-package axios
const axios = require("axios");
```

## Local Disk

[Section titled “Local Disk”](#local-disk)

```javascript
const path = require("path");


// Calculate the path to the temporary file
const filePath = path.join(process.env.TMP_DATA_DIR, "myfile.txt");


// Writing a file
const fs = require("fs");
fs.writeFileSync(filePath, "Hello from YepCode!");
```

## Datastore

[Section titled “Datastore”](#datastore)

```js
// Setting a value
await yepcode.datastore.set("key", "value");
// Setting a object value
await yepcode.datastore.set("key", JSON.stringify({ name: "John", age: 30 }));


// Getting a value
const value = await yepcode.datastore.get("key");


// Deleting a value
await yepcode.datastore.del("key");
```

## Storage

[Section titled “Storage”](#storage)

```js
const fs = require("node:fs");
const path = require("node:path");
const localPath = path.join(process.env.TMP_DATA_DIR, "localfile.txt");


// Uploading a file
await yepcode.storage.upload("path/myfile.txt", fs.createReadStream(localPath));


// Listing files
const files = await yepcode.storage.list();


// Downloading a file
const stream = await yepcode.storage.download("path/myfile.txt");
stream.pipe(fs.createWriteStream(localPath));


// Deleting a file
await yepcode.storage.delete("path/myfile.txt");
```

## Return Values

[Section titled “Return Values”](#return-values)

### Standard Return

[Section titled “Standard Return”](#standard-return)

```javascript
return { message: "Success!" };
```

### Custom HTTP Status Codes

[Section titled “Custom HTTP Status Codes”](#custom-http-status-codes)

* This is the format for custom HTTP status codes:

```javascript
return {
  status: 404,
  body: { message: "Not found" },
  headers: { "Content-Type": "application/json" }
};
```

## Transient Results

[Section titled “Transient Results”](#transient-results)

```javascript
return {
  transient: true,
  data: sensitiveData,
};
```

## Do & Don’t

[Section titled “Do & Don’t”](#do--dont)

**Do**

* Export `main` with `module.exports = { main }`.
* Use async/await for asynchronous work.
* Validate parameters at the start; throw clear errors for missing or invalid input.
* Use environment variables (e.g. `process.env.API_KEY`) for secrets; never hardcode them.
* Use try/catch around the main flow and log or re-throw with clear messages.
* Log important steps; never log secrets.

**Don’t**

* Never call `main()` in your code—YepCode invokes it.
* Never hardcode API keys, passwords, or tokens.
* Don’t forget to export: `module.exports = { main }`.
* Don’t use **var**; use **const** or **let**.
* Don’t ignore errors; wrap risky operations in try/catch.
* Don’t use dynamic module names: `yepcode.import(moduleName)` is wrong; use `yepcode.import("module-name")`.