Shared Require Complement

A companion to Luau Language Server for Lua/Luau projects using sharedRequire("..."). It handles module navigation, import editing, aliases, custom definitions and JSON shims. Type inference remains the language server's responsibility.

Requires VS Code 1.101 or newer and a local filesystem workspace, including the filesystem of a remote extension host. This minimum includes the Node.js 22 extension host required by the current Luau-LSP dependency; older editors can fail before this extension activates. The JohnnyMorganz.luau-lsp extension is installed as a dependency. Community project; not an official Roblox extension.

Everyday use

Use Go to Definition or Ctrl/Cmd+Click inside a sharedRequire string. Relative paths resolve from the importing file; workspace paths and alias targets resolve from the owning workspace folder. .luau, .lua, JSON files and init.lua/init.luau modules are supported.

Completion offers module imports on an otherwise empty identifier/declaration line. Type : on a blank line to choose a module from the picker. The insertion preserves indentation, quotes paths correctly and does not replace an existing right-hand expression or a line edited while the picker was open.

Rename files or folders through VS Code to update their imports in the same editor operation. Moving an importing file updates its own relative imports too. The extension preserves path style and adds an explicit extension when an extensionless path would resolve to a different module. Changes made by external filesystem tools are discovered by watchers, but cannot participate in VS Code's transactional rename edits.

Organize sharedRequire Imports sorts adjacent, simple local Name = sharedRequire(...) statements. It preserves comments and line endings, keeps repeated bindings in place, and does not cross block-comment, type-annotation or sharedRequire rebinding boundaries. Sorting can change module initialization order; keep order-sensitive imports separated and leave organize-on-save disabled for those projects.

Commands

Search for Shared Require in the command palette:

Manual synchronization has progress and cancellation. Details appear in the Shared Require Complement output channel. Editor features register immediately; automatic synchronization does not hold up activation on a network request or a notification.

Aliases and custom definitions

Example workspace settings:

{
  "sharedRequire.aliases.useDefaults": false,
  "sharedRequire.aliases.custom": {
    "@modules": "./src/modules",
    "@utils": "./src/utils"
  },
  "sharedRequire.types.definitionFiles": [
    "types/project.d.luau"
  ]
}

Default aliases remain available: @utils, @classes, @visuals, @services, @security, @modules, @libraries and @UILibrary point to their corresponding files/ directories. Alias matching uses the longest matching name. Reverse mapping prefers the most specific target directory. Absolute custom targets are supported.

Aliases and lint overrides share one generated base .luaurc in workspace storage. If a base configuration is already configured, its original file stays untouched: its mode, aliases and other fields are included in the generated overlay. Changes to the original file are watched and resynchronized. JSON with comments and trailing commas is accepted. Invalid or missing original configuration is reported instead of silently replaced. Updates are serialized and written atomically.

Custom .d.lua/.d.luau files resolve against their own workspace folders, then synchronize as absolute paths in workspace settings. Other definition packages are preserved. Files that override require or sharedRequire are excluded when sharedRequire.types.protectRequireGlobals is enabled; declarations mentioned only in comments are harmless. Unreadable files stop that synchronization step and preserve its previous configuration.

The bundled sharedRequire: typeof(require) declaration is copied to content-versioned extension storage. Its shared runtime entry can be global; project-specific custom definitions and alias paths are not written globally. Owned entries from older versions are migrated without clearing unrelated user settings.

Multi-root workspaces

Navigation, completion, JSON generation and rename analysis use each document's owning folder. Luau-LSP exposes a single window-wide base configuration and definition map. Custom definition files are combined. When the same alias maps to different absolute paths in different folders, alias synchronization reports that ambiguity and removes conflicting extension-owned mappings from the shared overlay. Use per-folder .luaurc files, aliases pointing to shared absolute locations, or separate windows. Local navigation continues to use the per-folder aliases.

JSON shims

A reference such as sharedRequire("./config.json") generates a neighboring config.json.lua for the language server. In typed mode, the shim returns a Luau table representing the JSON data, including properly quoted reserved-word keys and control characters. In any mode it returns nil :: any.

Typed generation falls back explicitly to any for malformed JSON, JSON containing null, files larger than 1 MiB, nesting deeper than 32 levels or more than 10,000 values. This avoids truncated shapes, invalid Luau and unbounded editor work.

New generated files carry a content checksum. A manually changed generated file, an unrelated Lua file or an unsaved shim is preserved. Legacy generated headers are migrated on synchronization. Cleanup is limited to enabled workspace folders and is suspended across those folders when any source inspection is incomplete, a relevant source document is dirty or the reference set changes during the scan. This also protects JSON imported from another workspace folder. Generation never writes beside JSON files outside the active workspace folders.

Patched language server

The default fork is TrapstarKS/luau-lsp. Patched-server settings are machine settings because they select executable code. Supported assets are macOS universal, Linux x64/ARM64 and Windows x64; Windows ARM64 uses the x64 asset through the operating system's emulation support.

Automatic updates respect a manually configured Luau-LSP executable. Running Sync Patched luau-lsp explicitly can select the managed binary for the current workspace; disabling the patched server restores the previous workspace selection.

Downloads have cancellation, timeouts and size bounds, and stream directly to disk. The release's SHA-256 digest is verified when supplied. Archives cannot escape staging directories, use symlinks or contain ambiguous server binaries. The extracted executable is checked and must start successfully before it becomes active. macOS signature repair runs only on the newly staged managed binary.

Verified installations are immutable and cached by repository, platform and release identity. A missing, changed or corrupted binary invalidates the cache even before the normal update interval. Failed checks do not advance that interval, and a working verified cache survives update failures. When enabled, official-server fallback only removes extension-owned overrides; custom executables are never deleted, signed or reset. Previous installation directories are retained so another editor window can keep using its binary.

Workspace trust and Roblox defaults

In Restricted Mode, read-only language navigation remains available. Automatic configuration changes, generated files, module-creation fixes and binary installation wait for workspace trust. Virtual workspaces are not supported.

For compatibility with existing users, this extension retains its Roblox defaults: luau-lsp.platform.type is roblox, and sourcemap generation is disabled by default. Rojo projects should explicitly enable their Luau-LSP sourcemap settings in workspace settings. Existing explicit settings take precedence over extension defaults.

Development and verification

Use Node.js 24 (.nvmrc) and the committed lockfile:

npm ci
npm run check
npm test
npm run package

check runs strict TypeScript compilation, typed ESLint and unit tests. test additionally launches real VS Code integration tests with the official Luau-LSP dependency and an isolated profile/workspace. Tests do not change your normal VS Code configuration. The first integration run downloads VS Code and its extension dependency. On Linux, run the host tests under xvfb-run -a when a display server is unavailable.

npm run smoke:server additionally downloads and verifies the actual patched server in the test cache, then checks alias imports, typed JSON shims and rejection of an invalid imported type. It requires network access and does not modify your editor settings.

Set VSCODE_TEST_VERSION=1.101.2 to test the minimum supported VS Code family. CI covers the minimum version on Linux and current stable VS Code on Linux, macOS and Windows. Compilation removes only out/ so deleted modules cannot accidentally remain in a package. The VSIX excludes test output, source maps, automation templates and development tooling.

src/features/shared/ contains lexical, filesystem and concurrency helpers. src/features/shared-require/ owns language features and JSON shims; src/features/sync/ owns their lifecycle and synchronization queue. The fork maintenance kit is documented in automation/luau-lsp-fork/README.md; it is not executed or packaged by the extension.