> Agent-readable docs index: /llms.txt. Download /docs.zip to grep all markdown files locally.

---
icon: puzzle
sidebar_position: 4
---

# Requirements

A **requirement** is a module your extension depends on. List dependencies in the
`requirements` array of your [extension manifest](/cs2/api_reference/extensions/anatomy).
Neverlose resolves and loads them **before** your `main.lua` runs. If your
extension has no dependencies, omit the array or leave it empty.

For example, declare a native module and then get its exported value with `require`:

```json extension.json
{
  "language": "lua",
  "requirements": ["http"]
}
```

```lua main.lua
local http = require("http")
```

## The three kinds of requirement

Which kind a requirement is comes from its **prefix**:

| Kind       | Form                        | Where it comes from                                                                 |
| ---------- | --------------------------- | ----------------------------------------------------------------------------------- |
| **Native** | `ffi`, `http`, `filesystem` | Capabilities built into the runtime. Use the library name without a prefix.         |
| **Market** | `neverlose/<name>`          | A library published on the Neverlose marketplace. Fetched and cached automatically. |
| **Local**  | `local/<name>`              | Another developer extension sitting in your own `extensions/` folder.               |

### Native modules

Declare each native capability your extension uses, then require it by its bare
name:

| Module                                             | Purpose                                                                                  |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| [`ffi`](/cs2/api_reference/lua/ffi)                | LuaJIT's foreign function interface. Also enables the related memory and vtable helpers. |
| [`http`](/cs2/api_reference/networking/http)       | HTTP requests and cookies.                                                               |
| [`filesystem`](/cs2/api_reference/data/filesystem) | File and directory operations.                                                           |

Calling `require` for one of these modules without a resolved requirement raises
an error. Capabilities needed by dependencies are resolved too, so a library's
`ffi` requirement also makes FFI available to the extension loading it.

Standard libraries such as `math`, `string`, and `table`, plus the built-in
`table.new` and `table.clear` modules, do not need manifest entries.

### Market modules

Reference a published library as `neverlose/<name>`. Neverlose resolves its
dependencies, downloads the required bundles, and caches them by name and
version.

An unversioned entry resolves to the latest version. In a local developer
extension, Neverlose writes that resolved version back into `extension.json`.
The package name below is illustrative; replace it with a published library
you use.

```json extension.json
{
  "language": "lua",
  "requirements": ["neverlose/example-library"]
}
```

You can **pin a published version** yourself by appending `:<number>`. Existing
explicit pins are preserved:

```json extension.json
{
  "language": "lua",
  "requirements": ["neverlose/example-library:5"]
}
```

Lua code can use the bare module name even when the manifest pins a version:

```lua main.lua
local library = require("neverlose/example-library")
```

The full pinned name, such as `require("neverlose/example-library:5")`, also
works when that version is resolved. Declare one version of each library in
your manifest.

Local developer extensions use source Lua and can only load open-source
marketplace dependencies. Closed-source extensions can also use open-source
libraries.

### Local modules

Reference a sibling extension as `local/<folder-name>`. For example,
`local/shared` refers to `extensions/shared/`. Its `main.lua` runs as a
dependency, and `require` returns its exported value. It does not need to be
enabled separately in the Extensions list.

Give the shared extension its own manifest:

```json shared/extension.json
{
  "language": "lua",
  "requirements": []
}
```

```lua shared/main.lua
local M = {}
function M.greet(name) return "hello, " .. name end
return M
```

Declare it in the consuming extension:

```json extension.json
{
  "language": "lua",
  "requirements": ["local/shared"]
}
```

```lua main.lua
local shared = require("local/shared")
print(shared.greet("world"))
```

Local dependencies must also be Lua extensions with a valid manifest and a
nonempty `main.lua`. Keep the dependency graph free of cycles: two libraries
cannot rely on each other's exports during initialization. Replace local
dependencies with published libraries before publishing your extension.

Native capabilities load first, followed by marketplace dependencies and local
dependencies, with dependencies loaded before their consumers. A missing or
unloadable requirement prevents the extension from starting.

## Requiring your own files

To split your extension across multiple `.lua` files, require each file by its
path relative to the extension root, where `main.lua` lives. Omit the `.lua`
extension. These files do not need manifest entries:

<Tree.Folder name="my-extension" defaultOpen>
  <Tree.File name="extension.json" />

  <Tree.File name="main.lua" />

  <Tree.File name="helpers.lua" />

  <Tree.Folder name="lib" defaultOpen>
    <Tree.File name="util.lua" />
  </Tree.Folder>
</Tree.Folder>

```lua main.lua
local helpers = require("helpers")    -- helpers.lua, next to main.lua
local util    = require("lib/util")   -- lib/util.lua, in a subdirectory
```

Each file can return a table of exports:

```lua lib/util.lua
local M = {}
function M.clamp(v, lo, hi) return math.min(math.max(v, lo), hi) end
return M
```

A few rules to keep in mind:

* **Use forward slashes** for subdirectories (`lib/util`), and **omit the `.lua`** extension.
* **Paths are relative to the extension root.** A file in `lib/` refers to a sibling as `require("lib/other")`. Absolute paths and `.` or `..` path segments are rejected.
* **Modules are cached.** Requiring the same file again returns its cached export. Return a table for reusable helpers; a module with no return value yields `true`.
* **Capability and library names take precedence.** Native, marketplace, and local module names are checked before files. Standard-library names are also resolved first, so `ffi.lua` and `math.lua` cannot replace those libraries. An undeclared native capability raises an error even if a same-named file exists.
* **Exports can be shared.** Marketplace and local dependencies are cached across extensions in the same Lua runtime. Avoid storing state specific to one extension in a shared library's export table.

## Managing requirements

Edit the `requirements` array by hand, or use the local extension's **Settings**
dialog. It identifies market, local, and native entries and offers an action to
update market libraries to their latest published version.

Settings saves requirement changes to `extension.json` immediately and reloads
an active extension when you close the dialog. Edits made in your editor follow
the [hot reload rules](/cs2/api_reference/extensions/anatomy#hot-reload).
