External Coding

When you enable the remote workspace, you get a ready-to-go Node project, recognized by most IDEs as a TypeScript-powered Node setup.

What's included:

• Prettier for code formatting with sensible defaults.
• ESLint for static code analysis, also with good defaults.
• Jest for running automated tests locally.

The web editor doesn't offer these features, so local editing significantly improves your developer experience, including the option to use AI agents to do the heavy lifting. For instance, floating promises can lead to race condition bugs that our web-based editor does not highlight. However, the default ESLint configuration in the remote file system includes a rule to warn against them.

Please turn off the auto-save feature in your IDE or code editor while developing locally. Auto-saving can put excessive strain on our resources by processing incomplete files. Instead, upload the file only after you have finished editing it. However, we recognize that AI agents usually make changes quite rapidly on the fly; this is allowed because this behavior usually cannot be avoided.

With our recommended setup using VS Code and the SFTP extension, you can configure the upload to occur automatically when you save the script. If you prefer to enable the auto-save feature, please adjust your IDE or code editor to save less frequently.

Please refrain from uploading files that are not necessary for the ScriptRunner Connect web app's functionality, to help us reduce overall traffic. This primarily includes the node_modules directory, which is generated when you run npm install or yarn. This folder contains a large number of files needed only for local development. When using our recommended VS Code and SFTP extension setup, we provide a configuration that automatically excludes the node_modules folder, so you don't need to take extra steps.

The remote file system is a ready-to-use TypeScript powered Node project. It requires no manual changes; just open it in a compatible IDE. Here's how the remote file system is organized:

• .vscode: Folder for VS Code specific configurations, our recommended code editor.
  • extensions.json: Recommended VS Code extensions, including ESLint for highlighting linter issues, Prettier for code formatting, and SFTP for seamless server integration.
  • settings.json: Recommended settings for VS Code.
• node: A folder for running code locally in Node, primarily for executing tests.
  • tests: Folder for developing local tests, a pre-configured location for Jest.
  • apiRegistry.ts: File for registering mocked Managed APIs to run code/tests locally.
  • global.d.ts: Global types for locally running scripts in Node.
  • jest.config.ts: Jest configuration file.
  • runtimeMocks.ts: Contains ScriptRunner Connect runtime -specific mocks for the Node runtime
  • tsconfig.json: TypeScript configuration for running code locally in Node.
• scripts: Folder containing workspace scripts.
  • api: A folder with local setups of API Connections with Managed APIs.

    Do not modify files here, as manual changes will be overwritten.

  • {scriptName}.ts: Workspace script(s).
• .prettierrc: Prettier configuration file.
• : .
• : Extended instructions for AI agents how to go about building test suite.
• : Extended instructions for AI agents that you can add on top of baseline instructions or overwrite baseline instructions. This file by default does not exist, you're expected to create it if you need to include additional instructions.
• eslint.config.json: ESLint configuration file.
• ev_params.ts: TypeScript types generated for configured parameters (environment variables).

  Do not modify this file, as changes will be overwritten. The default environment of your workspace is always used to generate parameter types, even if your default environment is not pointing to HEAD version.

• package.json: Node project configuration.
• tsconfig.base.json: Base TypeScript configuration file.
• tsconfig.json: TypeScript configuration file.

If you want to add third-party NPM packages to your local copy, please use our online package manager. Otherwise, you risk losing locally installed addition if you or anyone else uses the online package manager, which will overwrite the package.json file. However, for dependencies needed only for local use, you can add them directly to the ' devDependencies' section of your package.json. These changes won't be overwritten. This approach is recommended because it avoids unnecessarily pulling dev dependencies into the regular workspace, which could slow it down.

Our project has two different tsconfig.json files: one in the root directory and another inside the node folder. This setup exists because the API surface of ScriptRunner Connect's runtime differs from that of Node's API. However, you might still need to use Node's API when running code locally.

The project is configured to use ScriptRunner Connect's runtime types throughout, except within the node folder, where Node's API takes precedence. Therefore, scripts intended to run locally should be placed inside the node folder.

Example

For example, this distinction is evident when accessing the crypto.subtle namespace. Both ScriptRunner Connect and Node runtimes support the web.crypto standard, but ScriptRunner Connect's version is currently partial and lacks some methods. If you access crypto.subtle outside the node folder, you'll see the support for the following methods:

However, if you access the same namespace within node folder, you should see a longer list for full support: