Blog

How to write expressions in external (jsx) files

August 23, 2020

After Effects can import data in JSON (.json), CSV (.csv) and text (.txt) files, which you can then use in your expressions to create data driven animations.

In the same way, you can place JavaScript code in an external file, which you reference in your expression.

You do this by writing code in a modified JSON format and saving it as a file with the extension .jsx.

Check out our tutorial on writing .jsx files below:

Benefits

Writing parts of your expressions in external .jsx files, rather than directly in After Effects, means you can:

Write the code once, and then use it in multiple After Effects projects.

Updating the one .jsx file will update any expressions that reference that file, allowing you to re-use code across multiple projects and expressions.

Edit expressions in VS Code.

While the new expressions editor has some great features, writing in external files allows you to use more powerful code editors.

Improve performance.

After effects pre-processes expressions to allow for ExtendScript backwards compatibility. This pre-processing isn't done on code in external files, so there's a performance improvement for long expressions when written in .jsx files.

Standard JSON files

.jsx files are a modification of standard JSON format, which is a list of key value pairs, wrapped in braces ({}).

Since .jsx is a modification of the JSON standard, it helps to first understand how to write JSON files.

JSON can store values in the following data types:

Numbers
Strings
Booleans
Arrays
Objects
Null

For example:

example.json

json
{
  "someString": "Hello!",
  "someNumber": 5,
  "someBoolean": true,
  "someArray": ["elementOne"],
  "someObject": { "key": "value " },
  "someNull": null
}

JSON stands for "JavaScript Object Notation", and has a syntax resembling JavaScript objects.

In After Effects, you can then import this JSON file like you would any other footage item, and reference it in an expression with the following code:

sourceText

js
const jsonCode = footage("fileName.json").sourceData;
jsonCode.someString;

js
"Hello!";

Collecting files

After Effects doesn't count footage items that are only referenced in expressions as "used". This means if you Collect Files or Reduce Project, these files will be removed.

For this reason it's best to add any JSON, .jsx, or other data files used in your expressions as layers in any compositions where they're referenced. You can do this by dragging them into the timeline as you would any other footage item.

Writing `.jsx` files

As you can see, JSON files can only store data - not logic, or executable code. In JavaScript terms, they can't contain methods, which are functions attached to an object.

To get around this limitation, After Effects uses a modified JSON syntax that allows for the embedding of functions in JSON files.

Since this isn't valid JSON syntax, you need to change the extension to .jsx. This tells After Effects not to parse the file as JSON, which would result in an error.

You can then add functions to your JSON file with the following syntax:

example.json

js
{
  "someString": "Hello!",
  "someNumber": 5,
  "someFunction": function(inputParamaters) {
    return "function in an external file!";
  },
}

And call the function in an expression:

sourceText

js
const jsxCode = footage("fileName.jsx").sourceData;
jsxCode.someFunction();

js
"function in an external file!";

This function can contain any standard JavaScript, which you call from within your expressions.

After Effects will reload your .jsx footage item when it changes, allowing you see the edits you make to the file quickly:

Loose Syntax

Since the parser for .jsx files is looser than the JSON parser, you can structure the code in a way that more closely resembles JavaScript.

While it's further from the original JSON, making your .jsx files closer to standard JavaScript will make them easier to read, as well as improve syntax highlighting and error checking in your editor.

The allowed syntax is the same as a standard JavaScript object, except without the variable declaration.

For example if you change the earlier code to a standard JavaScript object:

example.jsx

js
const jsxCode = {
  // comments are also allowed
  someString: "Hello!",
  someNumber: 5,
  someFunction(inputParamaters) {
    return "function in an external file!";
  },
};

js
Unexpected token "const"

Will result in an error, while:

example.jsx

js
{
  // comments are also allowed
  someString: "Hello!",
  someNumber: 5,
  someFunction(inputParamaters) {
    return "function in an external file!";
  },
}

Works as expected.

Syntax Differences

Writing JavaScript in external files has some stricter requirements than writing within After Effects, as the pre-processing done on expressions isn't done the code in .jsx files.

For a full list of the differences between writing expression in After Effects and in .jsx files, see this article by Adobe.

An overview of these differences is below, but it's recommended to read the article above for a comprehensive explanation.

Prefixing native attributes and methods

You need to prefix any native attributes or methods with either:

thisLayer or
thisProperty

For example:

js
// layer attributes and methods
thisLayer.time;
thisLayer.transform;
thisLayer.name;
thisLayer.comp();
thisLayer.sourceRectAtTime();
// property attributes and methods
thisProperty.velocity;
thisProperty.speed;
thisProperty.numKeys;
thisProperty.wiggle();
thisProperty.valueAtTime();
thisProperty.loopIn();

Vector math functions

After Effects automatically inserts the appropriate vector math functions (such as add(), sub(), and mul()) into your expressions during pre-processing.

This because you can't perform math functions on Arrays in JavaScript, for example:

js
[960, 540] + 200;

js
"960,540200";

Will coerce the array to a string. In an external file, you need to wrap it in one of the vector math functions:

js
thisLayer.add([960, 540], 200);

js
[1160, 540];

For a deeper look at how this processing works, see the article: What happens during expression pre-processing

expressions-library-template

We have a template for creating .jsx expression libraries, which will allow you to write expressions in TypeScript.

It's allows you to write expressions with the benefits of:

Type safety
Auto completion
Testing
Releases and versioning

For more information, see the article on writing expressions in TypeScript.