Skip to main content

Plugins

The BrighterScript compiler is extensible using JavaScript plugins.

Configuration​

Declarative configuration​

You can refer to node scripts / npm modules directly in the bsconfig.json.

Those plugins will be loaded by the VSCode extension and can provide live diagnostics within the editor.

{
    "plugins": [
        "./scripts/myPlugin.js",
        "@rokucommunity/bslint"
    ]
}

Usage on the CLI​

npx bsc --plugins "./scripts/myPlugin.js" "@rokucommunity/bslint"

Programmatic configuration​

When using the compiler API directly, plugins can directly reference your code:

import { ProgramBuilder } from 'brighterscript';
import myPlugin from './myPlugin';

const builder = new ProgramBuilder();
builder.addPlugin(myPlugin);
builder.run(/*...*/);

Creating a plugin​

Naming conventions​

While there are no restrictions on plugin names, it helps others to find your plugin on npm when you follow these naming conventions:

  • Unscoped: If your npm package name won’t be scoped (doesn’t begin with @), then the plugin name should begin with bsc-plugin-, such as bsc-plugin-auto-findnode.
  • Scoped: If your npm package name will be scoped, then the plugin name should be in the format of @<scope>/bsc-plugin-<plugin-name> such as @rokucommunity/bsc-plugin-auto-findnode or even @<scope>/bsc-plugin such as @maestro/bsc-plugin.

Compiler events​

When does BrighterScript run?​

Most events come in three phases: before<Event>, <event> (the "during" phase), and after<Event>. Every plugin's handler for a phase runs before the next phase starts.

BrighterScript's own built-in work (parsing, validation, hovers, completions, transpiling, writing files, etc.) is the last participant in the "during" phase of every event. So:

  • before<Event>: runs before BrighterScript has done anything for this event.
  • <event>: runs before BrighterScript. Use this to contribute results alongside BrighterScript or to handle something yourself first. For example, providing a file in provideFile keeps BrighterScript from providing that file, and adding a file to processedFiles in writeFile keeps BrighterScript from writing it.
  • after<Event>: runs after BrighterScript. BrighterScript's results are available here, so this is the place to inspect, modify, or remove them.

There are two exceptions, where BrighterScript goes first in the "during" phase:

  • validateFile: BrighterScript registers the file's declarations (functions, classes, variables, etc.) first, so your validateFile handler can look up the file's symbols and types. BrighterScript's file diagnostics are still added in afterValidateFile.
  • validateScope: BrighterScript validates scopes first, so your validateScope handler runs after BrighterScript's scope validation.

Full compiler lifecycle (<BrighterScript ...> marks where BrighterScript's own work happens):

  • beforeProvideProgram
  • provideProgram
  • afterProvideProgram
    • afterProvideScope ("source" scope)
    • For each physical file:
      • beforeProvideFile
      • provideFile
      • <BrighterScript provides the file>
      • afterProvideFile
    • For each physical and virtual file
      • beforeAddFile
      • addFile
      • afterAddFile
      • beforeProvideScope (component scope)
      • provideScope (component scope)
      • afterProvideScope (component scope)
    • beforeValidateProgram
    • validateProgram
    • For each file:
      • beforeValidateFile
      • <BrighterScript registers the file's declarations>
      • validateFile
      • <BrighterScript validates the file>
      • afterValidateFile
    • For each scope:
      • beforeValidateScope
      • <BrighterScript validates the scope>
      • validateScope
      • afterValidateScope
    • <BrighterScript validates the program>
    • afterValidateProgram
  • <BrighterScript prepares the build>
  • beforeBuildProgram
  • buildProgram
    • beforePrepareProgram
    • prepareProgram
    • For each file:
      • beforePrepareFile
      • prepareFile
      • <BrighterScript prepares the file>
      • afterPrepareFile
    • afterPrepareProgram
    • beforeSerializeProgram
    • serializeProgram
    • For each file:
      • beforeSerializeFile
      • serializeFile
      • <BrighterScript serializes the file>
      • afterSerializeFile
    • afterSerializeProgram
    • beforeWriteProgram
    • writeProgram
    • For each serialized file:
      • beforeWriteFile
      • writeFile
      • <BrighterScript writes the file>
      • afterWriteFile
    • afterWriteProgram
  • afterBuildProgram
  • beforeRemoveProgram
  • removeProgram
  • afterRemoveProgram

Language server​

Once the program has been validated, the language server runs a special loop - it never reaches the publishing steps.

When a file is removed:

  • beforeRemoveFile
  • beforeRemoveScope (component scope)
  • afterRemoveScope (component scope)
  • afterRemoveFile

When a file is added:

  • beforeProvideFile
  • afterProvideFile
  • afterProvideScope (component scope)
  • afterValidateFile

When any file is modified:

  • Remove file
  • Add file

After file addition/removal (note: throttled/debounced):

  • beforeValidateProgram
  • For each invalidated/not-yet-validated file
    • beforeValidateFile
    • validateFile
    • afterValidateFile
  • For each invalidated scope:
    • beforeValidateScope
    • afterValidateScope
  • afterValidateProgram

Code Actions

  • provideCodeActions

Completions

  • beforeProvideCompletions
  • provideCompletions
  • afterProvideCompletions

Hovers

  • beforeProvideHover
  • provideHover
  • afterProvideHover

Semantic Tokens

  • provideSemanticTokens

Compiler API​

Objects in the BrighterScript compiler dispatch a number of events that you can listen to. These events allow you to peek / modify the objects that the compiler manipulates.

The top level object is the ProgramBuilder which runs the overall process: preparation, running the compiler (Program) and producing the output.

Program is the compiler itself; it handles the creation of program objects (Scope, BrsFile, XmlFile) and overal validation.

BrsFile is a .brs or .bs file; its AST can be modified by a plugin.

XmlFile is a component; it doesn't have a proper AST currently but it can be "patched".

Scope is a logical group of files; for instance source files, or each component's individual scope (XML definition, related components and imported scripts). A file can be included in multiple scopes.

Files are superficially validated after parsing, then re-validated as part of the scope they are included in.

API definition​

Here are some important interfaces. You can view them in the code at this link.

export type CompilerPluginFactory = (options?: PluginFactoryOptions) => CompilierPlugin;

export interface CompilerPlugin {
    name: string;
    /**
     * Called before a new program is created
     */
    beforeProvideProgram?(event: BeforeProvideProgramEvent): any;
    /**
     * Called after a new program is created
     */
    afterProvideProgram?(event: AfterProvideProgramEvent): any;


    /**
     * Called before the program gets prepared for building
     */
    beforePrepareProgram?(event: BeforePrepareProgramEvent): any;
    /**
     * Called when the program gets prepared for building
     */
    prepareProgram?(event: PrepareProgramEvent): any;
    /**
     * Called after the program gets prepared for building
     */
    afterPrepareProgram?(event: AfterPrepareProgramEvent): any;


    /**
     * Called before the entire program is validated
     */
    beforeValidateProgram?(event: BeforeValidateProgramEvent): any;
    /**
     * Called before the entire program is validated
     */
    validateProgram?(event: ValidateProgramEvent): any;
    /**
     * Called after the program has been validated
     */
    afterValidateProgram?(event: AfterValidateProgramEvent): any;

    /**
     * Called right before the program is disposed/destroyed
     */
    beforeRemoveProgram?(event: BeforeRemoveProgramEvent): any;

    /**
     * Emitted before the program starts collecting completions
     */
    beforeProvideCompletions?(event: BeforeProvideCompletionsEvent): any;
    /**
     * Use this event to contribute completions
     */
    provideCompletions?(event: ProvideCompletionsEvent): any;
    /**
     * Emitted after the program has finished collecting completions, but before they are sent to the client
     */
    afterProvideCompletions?(event: AfterProvideCompletionsEvent): any;


    /**
     * Called before the `provideHover` hook. Use this if you need to prepare any of the in-memory objects before the `provideHover` gets called
     */
    beforeProvideHover?(event: BeforeProvideHoverEvent): any;
    /**
     * Called when bsc looks for hover information. Use this if your plugin wants to contribute hover information.
     */
    provideHover?(event: ProvideHoverEvent): any;
    /**
     * Called after the `provideHover` hook. Use this if you want to intercept or sanitize the hover data (even from other plugins) before it gets sent to the client.
     */
    afterProvideHover?(event: AfterProvideHoverEvent): any;

    /**
     * Called after a scope was created
     */
    afterProvideScope?(event: AfterProvideScopeEvent): any;

    beforeRemoveScope?(event: BeforeRemoveProgramEvent): any;
    removeScope?(event: RemoveScopeEvent): any;
    afterRemoveScope?(event: AfterRemoveScopeEvent): any;

    beforeValidateScope?(event: BeforeValidateScopeEvent): any;

    /**
     * Called before the `provideDefinition` hook
     */
    beforeProvideDefinition?(event: BeforeProvideDefinitionEvent): any;
    /**
     * Provide one or more `Location`s where the symbol at the given position was originally defined
     * @param event
     */
    provideDefinition?(event: ProvideDefinitionEvent): any;
    /**
     * Called after `provideDefinition`. Use this if you want to intercept or sanitize the definition data provided by bsc or other plugins
     * @param event
     */
    afterProvideDefinition?(event: AfterProvideDefinitionEvent): any;


    /**
     * Called before the `provideReferences` hook
     */
    beforeProvideReferences?(event: BeforeProvideReferencesEvent): any;
    /**
     * Provide all of the `Location`s where the symbol at the given position is located
     * @param event
     */
    provideReferences?(event: ProvideReferencesEvent): any;
    /**
     * Called after `provideReferences`. Use this if you want to intercept or sanitize the references data provided by bsc or other plugins
     * @param event
     */
    afterProvideReferences?(event: AfterProvideReferencesEvent): any;


    /**
     * Called before the `provideDocumentSymbols` hook
     */
    beforeProvideDocumentSymbols?(event: BeforeProvideDocumentSymbolsEvent): any;
    /**
     * Provide all of the `DocumentSymbol`s for the given file
     * @param event
     */
    provideDocumentSymbols?(event: ProvideDocumentSymbolsEvent): any;
    /**
     * Called after `provideDocumentSymbols`. Use this if you want to intercept or sanitize the document symbols data provided by bsc or other plugins
     * @param event
     */
    afterProvideDocumentSymbols?(event: AfterProvideDocumentSymbolsEvent): any;


    /**
     * Called before the `provideWorkspaceSymbols` hook
     */
    beforeProvideWorkspaceSymbols?(event: BeforeProvideWorkspaceSymbolsEvent): any;
    /**
     * Provide all of the workspace symbols for the entire project
     * @param event
     */
    provideWorkspaceSymbols?(event: ProvideWorkspaceSymbolsEvent): any;
    /**
     * Called after `provideWorkspaceSymbols`. Use this if you want to intercept or sanitize the workspace symbols data provided by bsc or other plugins
     * @param event
     */
    afterProvideWorkspaceSymbols?(event: AfterProvideWorkspaceSymbolsEvent): any;


    provideSemanticTokens?: PluginHandler<ProvideSemanticTokensEvent>;
    //scope events
    validateScope?(event: ValidateScopeEvent): any;
    afterValidateScope?(event: BeforeValidateScopeEvent): any;

    provideCodeActions?(event: ProvideCodeActionsEvent): any;
    provideSemanticTokens?(event: ProvideSemanticTokensEvent): any;


    /**
     * Called before plugins are asked to provide files to the program. (excludes virtual files produced by `provideFile` events).
     * Call the `setFileData()` method to override the file contents.
     */
    beforeProvideFile?(event: BeforeProvideFileEvent): any;
    /**
     * Give plugins the opportunity to handle processing a file. (excludes virtual files produced by `provideFile` events)
     */
    provideFile?(event: ProvideFileEvent): any;
    /**
     * Called after a file was added to the program. (excludes virtual files produced by `provideFile` events)
     */
    afterProvideFile?(event: AfterProvideFileEvent): any;


    /**
     * Called before a file is added to the program.
     * Includes physical files as well as any virtual files produced by `provideFile` events
     */
    beforeAddFile?(event: BeforeAddFileEvent): any;
    /**
     * Called after a file has been added to the program.
     * Includes physical files as well as any virtual files produced by `provideFile` events
     */
    afterAddFile?(event: AfterAddFileEvent): any;

    /**
     * Called before a file is removed from the program. This includes physical and virtual files
     */
    beforeRemoveFile?(event: BeforeRemoveFileEvent): any;
    /**
     * Called after a file has been removed from the program. This includes physical and virtual files
     */
    afterRemoveFile?(event: AfterRemoveFileEvent): any;


    /**
     * Called before each file is validated
     */
    beforeValidateFile?(event: BeforeValidateFileEvent): any;
    /**
     * Called during the file validation process. If your plugin contributes file validations, this is a good place to contribute them.
     */
    validateFile?(event: ValidateFileEvent): any;
    /**
     * Called after each file is validated
     */
    afterValidateFile?(event: AfterValidateFileEvent): any;


    /**
     * Called right before the program builds (i.e. generates the code and puts it in the outDir
     */
    beforeBuildProgram?(event: BeforeBuildProgramEvent): any;
    /**
     * Called right after the program builds (i.e. generates the code and puts it in the outDir
     */
    afterBuildProgram?(event: AfterBuildProgramEvent): any;


    /**
     * Before preparing the file for building
     */
    beforePrepareFile?(event: BeforePrepareFileEvent): any;
    /**
     * Prepare the file for building
     */
    prepareFile?(event: PrepareFileEvent): any;
    /**
     * After preparing the file for building
     */
    afterPrepareFile?(event: AfterPrepareFileEvent): any;


    /**
     * Before the program turns all file objects into their final buffers
     */
    beforeSerializeProgram?(event: BeforeSerializeProgramEvent): any;
    /**
     * Emitted right at the start of the program turning all file objects into their final buffers
     */
    serializeProgram?(event: SerializeProgramEvent): any;
    /**
     * After the program turns all file objects into their final buffers
     */
    afterSerializeProgram?(event: AfterSerializeProgramEvent): any;


    /**
     * Before turning the file into its final contents
     */
    beforeSerializeFile?(event: BeforeSerializeFileEvent): any;
    /**
     * Turn the file into its final contents (i.e. transpile a bs file, compress a jpeg, etc)
     */
    serializeFile?(event: SerializeFileEvent): any;
    /**
     * After turning the file into its final contents
     */
    afterSerializeFile?(event: AfterSerializeFileEvent): any;


    /**
     * Called before any files are written
     */
    beforeWriteProgram?(event: BeforeWriteProgramEvent): any;
    /**
     * Called after all files are written
     */
    afterWriteProgram?(event: AfterWriteProgramEvent): any;


    /**
     * Before a file is written to disk. These are raw files that contain the final output. One `File` may produce several of these
     */
    beforeWriteFile?(event: BeforeWriteFileEvent): any;
    /**
     * Called when a file should be persisted (usually writing to storage). These are raw files that contain the final output. One `File` may produce several of these.
     * When a plugin has handled a file, it should be pushed to the `handledFiles` set so future plugins don't write the file multiple times
     */
    writeFile?(event: WriteFileEvent): any;
    /**
     * Before a file is written to disk. These are raw files that contain the final output. One `File` may produce several of these
     */
    afterWriteFile?(event: AfterWriteFileEvent): any;
}

// related types:
interface FileObj {
    src: string;
    dest: string;
}

interface TranspileObj {
    file: File;
    outputPath: string;
}

type ValidateHandler = (scope: Scope, files: File[], callables: CallableContainerMap) => void;
interface CallableContainerMap {
    [name: string]: CallableContainer[];
}
interface CallableContainer {
    callable: Callable;
    scope: Scope;
}

PluginFactory​

To register a plugin, you need to have a default export that returns a factory. BrighterScript will call this factory once for every instance of a program that needs the plugin. This means that you might have multiple instances of a plugin in one NodeJS process (one for each BrighterScript project).

export default function () {
    return {
        name: 'Name of your plugin'
    };
}

BrighterScript v0 compatibility​

v1 is a rewrite of BrighterScript which includes some significant breaking changes. This has caused challenges with BrighterScript plugins, as you need to maintain separate versions for v0 and v1. You can utilize the pluginOptions.version property in your factory to determine what BrighterScript version is running your plugin, and adjust accordingly.

This options object is only available starting with BrighterScript v0.69.4 and v1.0.0-alpha.45. It's important to support backwards compatibility that an undefined version value be treated as a v0 plugin.

Here's a small example:

export default function (pluginOptions: PluginOptions) {
    if(semver.major(pluginOptions?.version) === '1') {
        return {
            name: 'v1 version of your plugin!'
        };
    } else {
        return {
            name: 'v0 version of your plugin'
        };
    }
}

Plugin API​

Plugins are JavaScript modules dynamically loaded by the compiler. Their entry point is a default function that returns an object that follows the CompilerPlugin interface.

To walk/modify the AST, a number of helpers are provided in brighterscript/dist/parser/ASTUtils.

Conditional compilation​

Walks skip the inactive branches of #if / #else if / #else statements, unless the walk mode includes InternalWalkMode.visitFalseConditionalCompilationBlocks. Which branches are active depends on the bs_const values from the manifest, and on the #const declarations that precede each #if.

The walk works out which branches are active and stores the answers on the AST, much like it sets node.parent:

  • Only a full walk from the root computes the answers. A full walk starts at the file's ast and walks statements and expressions and steps into functions (for example ast.link(), or the walk during validation). It starts from the manifest bs_const values (ast.bsConsts), adds each active #const as it reaches it in source order, and stores the result of each #if on the statement (isConditionTrue, isConditionDeclared). Like parent, a full walk that is cancelled part way (such as findChild, which stops at the first match) only updates the nodes it reached.
  • Every other walk follows the stored answers. A walk that starts below the root (such as callExpression.walk(...)) or skips part of the tree (such as one that does not step into functions) has not seen every #const before the nodes it visits, so it can't work out the conditions itself. An #if / #else if / #else / #end if chain compiles exactly one of its branches. When this walk reaches a chain, it doesn't check the conditions again: it goes into the branch the last full walk chose (from each statement's stored isConditionTrue), and skips the others, along with any #if or #const inside them.
  • Every walk sets node.isActive from the parent's value and the parent's #if result. Like parent, it is undefined until the node has been walked. A full walk also marks the nodes of the inactive branches, even though the visitor never sees them. The compiler treats undefined as active, so nodes a plugin creates are included until a walk says otherwise. Check isActive === false to find inactive code.
  • Class members follow isActive too. ClassStatement.methods, fields and members list the members of every branch, since every branch is transpiled. memberMap prefers a member that is not inactive when branches declare the same name.
  • Edits apply at the next full walk. A plugin that wants to change a constant should insert a #const statement into the AST. That, like any other edit to the AST (such as a changed #if condition or an inserted #if statement), applies at the next full walk, such as the one when the file is validated. Until then, the stored answers describe the AST as it was. An #if that no full walk has reached yet has no stored answer, and is walked as if its condition were false.
  • Don't pass bsConsts in the walk options. The full walk fills it in itself as it moves through the tree. If a walk is given a bsConsts map, it evaluates every #if and #const it reaches against that map and overwrites the stored answers. The rest of the program (validation, transpile, editor features) then uses those answers until the next full walk. A walk that starts below the root also misses any #const above where it starts, so its answers can be wrong even for the constants you gave it. To change the constants, set ast.bsConsts or insert a #const statement, and let the next full walk apply it.

Lexer and parser diagnostics inside an inactive branch are not reported, since the device never compiles that code. Instead, each inactive branch body gets an inactive-conditional-compile-branch diagnostic with Hint severity and the Unnecessary tag, which editors show by fading the code. Plugin tests that expect zero diagnostics on code with an inactive #if will see these hints.

Working with TypeScript​

It is highly recommended to use TypeScript as intellisense helps greatly writing code against new APIs.

Using ts-node to transpile plugin dynamically​

The ts-node module can transpile typescript on the fly. This is by far the easiest way to develop a BrighterScript plugin, as you can eliminate the manual typescript transpile step.

# install modules needed to compile a plugin
npm install brighterscript typescript @types/node ts-node -D

#run the brighterscript cli and use ts-node to dynamically transpile your plugin
npx bsc --sourceMap --require ts-node/register --plugins myPlugin.ts

The require flag can also be set in the bsconfig.json, simplifying your bsc command arguments.

{
    "require": ["ts-node/register"]
}

Transpiling manually​

If you would prefer to transpile your plugin manually, you can follow these steps:

# install modules needed to compile a plugin
npm install brighterscript typescript @types/node -D

# transpile to JS (with source maps for debugging)
npx tsc myPlugin.ts -m commonjs --sourceMap

# add --watch for continuous transpilation
npx tsc myPlugin.ts -m commonjs --sourceMap --watch

Example diagnostic plugins​

Diagnostics must run every time it is relevant:

  • Files have one out-of-context validation step (afterValidateFile),
  • Scopes are validated once all the the files have been collected (before/afterValidateScope).

Note: in a language-server context, Scope validation happens every time a file changes.

To add a diagnostic, register it with the DiagnosticManager, available from the program property of any event.

// bsc-plugin-no-underscores.ts
import { CompilerPlugin, File, isBrsFile } from 'brighterscript';

// plugin factory
export default function () {
    return {
        name: 'no-underscores',
        // post-parsing validation
        afterValidateFile: (event: AfterValidateFileEvent) => {
            if (isBrsFile(event.file)) {
                // clear existing diagnostics
                event.program.diagnosticManager.clearByContext({file: file, tag: 'no-underscores-plugin'});

                // visit function statements and validate their name
                event.file.ast.walk(createVisitor({
                    FunctionStatement: (funcStmt) => {
                        if (funcStmt.tokens.name.text.includes('_')) {
                            event.program.diagnostics.register([{
                                code: 9000,
                                message: 'Do not use underscores in function names',
                                location: util.getLocation(funcStmt.tokens.name)
                            }]);
                        }
                    }
                }, {
                    walkMode: WalkMode.visitStatements
                });
            }
        }
    } as CompilerPlugin;
};

Locations​

To keep memory down, tokens and AST nodes don't store a Location. Instead, each one stores where it starts and ends, counted from the start of the file (startPosition and endPosition), plus a reference to info about the file it was parsed from (sourceInfo), which is shared by everything from the same parse. sourceInfo.linePositions holds where each line of the file starts, which is how positions get converted to lines and characters.

Positions are the gaps between characters, like an editor cursor (and like an LSP Position). For a file that starts with print, the print token's startPosition is 0 (before the p) and its endPosition is 5 (after the t), so endPosition - startPosition is its length.

Build the line/character Location on demand with util.getLocation():

const location = util.getLocation(funcStmt.tokens.name); // { uri, range }

A node's bounds are computed once, when it's constructed, from the children and tokens it's given. They describe where the node came from in the original source, so they don't change if a plugin edits the AST afterwards (i.e. adding statements to a block doesn't move the block).

util.getLocation() returns undefined for synthetic tokens and nodes (ones that were created in code rather than parsed from a file), since they have no position. A synthetic node won't get a source map entry, and diagnostics can't point at it.

A position describes where the code came from in the original source, so it's used as-is for source maps and diagnostics. Don't change the position of a parsed token or node. Only give one to a synthetic token or node you're creating:

  • Borrow it from a real token or node in the same file (preferred): util.setBounds(node, someToken). This shares the file's real sourceInfo, so the node combines correctly with the rest of that file's AST. The create* functions do the same when given a token or node: createToken(TokenKind.Identifier, 'name', someToken).
  • From a Location in a file: util.setLocation(node, location, file.sourceInfo). This maps the location into that file, so the node combines with the rest of its AST. If the location is in a different file (or its lines aren't in the file), the node is left without a position. To pass one to a create* function, convert it first: createToken(TokenKind.Identifier, 'name', util.setLocation({} as Locatable, location, file.sourceInfo)).
  • From a Location without the file's source: the create* functions also accept a Location directly, and assigning node.location or token.location moves an item to that location (see util.assignLocation()). When the file's source isn't known, the position goes in a placeholder source for the location's uri. util.getLocation() gives back the same location, and items placed this way combine with each other, but not with the file's parsed AST, so prefer the options above when you can.

Code parsed from a snippet (i.e. Parser.parse('...') without a srcPath) has positions, but no uri. Those positions aren't in the file the code is added to, so lookups by position in that file (hover, definition, etc.) skip it, it isn't included in the bounds of nodes that also contain code from a file, and it doesn't get source map entries.

Location is only used for language server output (diagnostics, hovers, etc.), so use util.getLocation() when you need one. Tokens and nodes still have location and range properties to help existing plugins migrate, but they're deprecated and will be removed in a future release. They build a new Location on every read (so don't compare them with ===). Tokens created by hand (i.e. { kind: ..., text: ... } or { ...token }) don't have them, so create tokens with createToken() or util.cloneToken() instead.

Modifying code​

Sometimes plugins will want to modify code before the project is transpiled. While you can technically edit the AST directly at any point in the file's lifecycle, this is not recommended as those changes will remain changed as long as that file exists in memory and could cause issues with file validation if the plugin is used in a language-server context (i.e. inside vscode).

Instead, we provide an instace of an Editor class in the beforePrepareFile event that allows you to modify AST before the file is transpiled, and then those modifications are undone afterPrepareFile.

For example, consider the following brightscript code:

sub main()
    print "hello <FIRST_NAME>"
end sub

Here's the plugin:

import { CompilerPlugin, BeforeFileTranspileEvent, isBrsFile, WalkMode, createVisitor, TokenKind } from 'brighterscript';

// plugin factory
export default function () {
    return {
        name: 'replacePlaceholders',
        // transform AST before transpilation
        beforePrepareFile: (event: BeforeFileTranspileEvent) => {
            if (isBrsFile(event.file)) {
                event.file.ast.walk(createVisitor({
                    LiteralExpression: (literal) => {
                        //replace every occurance of <FIRST_NAME> in strings with "world"
                        if (literal.token.kind === TokenKind.StringLiteral && literal.token.text.includes('<FIRST_NAME>')) {
                            event.editor.setProperty(literal.token, 'text', literal.token.text.replace('<FIRST_NAME>', 'world'));
                        }
                    }
                }), {
                    walkMode: WalkMode.visitExpressionsRecursive
                });
            }
        }
    } as CompilerPlugin;
};

This plugin will search through every LiteralExpression in the entire project, and every time we find a string literal, we will replace <FIRST_NAME> with world. This is done with the event.editor object. editor allows you to apply edits to the AST, and then the BrighterScript compiler will undo those edits once the file has been transpiled.

Remove Comment and Print Statements​

Another common use case is to remove print statements and comments. Here's a plugin to do that:

Note: Comments are not regular nodes in the AST. They're considered "trivia". To access them, you need to ask each AstNode for its trivia. to help with this, we've included the AstNode visitor method. Here's how you'd do that:

import { Plugin, BeforePrepareFileEvent, isBrsFile, WalkMode, createVisitor, TokenKind, AstNode, EmptyStatement } from 'brighterscript';

export default function (): Plugin {
    return {
        name: 'removeCommentAndPrintStatements',
        beforePrepareFile: (event: BeforePrepareFileEvent) => {
            if (!isBrsFile(event.file)) {
                return;
            }
            //delete comments from the EOF token
            event.editor.arraySplice(event.file.parser.eofToken.leadingTrivia, 0, Number.MAX_SAFE_INTEGER);

            event.file.ast.walk(createVisitor({
                PrintStatement: (node: AstNode, _parent, owner, key) => {
                    return new EmptyStatement();
                },
                AstNode: (node: AstNode, _parent, owner, key) => {
                    const trivia = node.leadingTrivia;
                    for (let i = 0; i < trivia.length; i++) {
                        if (trivia[i]?.kind === TokenKind.Comment) {
                            //remove this token
                            event.editor.arraySplice(trivia, i, 1);
                            //replay this index again for the new item that took our spot since we deleted from the array
                            i--;
                        }
                    }
                }
            }), {
                walkMode: WalkMode.visitAllRecursive
            });
        }
    };
}

Modifying bsconfig.json via a plugin​

In some cases you may want to modify the project's configuration via a plugin, such as to change settings based on environment variables or to dynamically modify the project's files array. Plugins may do so in the beforeProvideProgram step. For example, here's a plugin which adds an additional file to the build:

import { CompilerPlugin, ProgramBuilder } from 'brighterscript';

export default function plugin() {
    return {
        name: 'addFilesDynamically',
        beforeProvideProgram: (builder: ProgramBuilder) => {
            if (!builder.options.files) {
                builder.options.files = [];
            }

            builder.options.files.push({
                src: "path/to/plugin/file.bs",
                dest: "some/destination/path/goes/here"
            })
        }
    } as CompilerPlugin;
}

File API​

By default, BrighterScript only parses files that it knows how to handle. Generally this includes .xml files in the compontents folder, .brs, .bs and .d.bs files. Other files may be handled in the future, such as manifest, .ts and possibly more. All other files are loaded into the program as AssetFile types and have no special handling or processing.

Plugins can provide files by contributing a provideFile function. BrighterScript will perform all of its file providing (like for .xml or .brs files) at the end of provideFile once every plugin had a chance to provide their own files. If you need to handle files before brighterscript does (like if you wanted to parse the .brs file instead of letting BrighterScript do it), you should do this in the provideFile event.

Your plugin may want to add enhanced features for file types (such as parsing javascript and converting it to BrightScript). BrighterScript supports this by asking plugins to "provide" file objects for a given file path.

Here's a sample plugin showing how to handle this:

import { ProvideFileEvent, CompilerPlugin, BrsFile } from 'brighterscript';

export default function plugin() {
    return {
        name: 'removeCommentAndPrintStatements',
        provideFile: (event: ProvideFileEvent) => {
            //convert all javascript files into .brs files (magically!)
            if (event.srcExtension === '.js') {
                //get the file contents as a string
                const jsCode = event.getFileData().toString();

                //somehow magically convert javascript code to brightscript code
                const brsCode = convertJsToBrsUsingMagic(jsCode);

                //create a new BrsFile which will hold the final brs code after the js file was parsed
                const file = event.fileFactory.BrsFile({
                    srcPath: event.srcPath,
                    //rename the .js extension to .brs
                    destPath: event.destPath.replace(/\.js$/, '.brs')
                });
                //parse the generated brs code
                file.parse(brsCode);

                //add this brs file to the event, which is how you "provide" the file
                event.files.push(file);
            }
        }
    } as CompilerPlugin;
}

Multiple files​

Plugins can also provide multiple files from a single physical file. Consider this example:


import { BeforeProvideFileEvent, CompilerPlugin, BrsFile, XmlFile, trim } from 'brighterscript';

export default function plugin() {
    return {
        name: 'componentPlugin',
        beforeProvideFile: (event: BeforeProvideFileEvent) => {
            // source/buttons.component.bs

            event.files
            //split a .component file into a .brs and a .xml file
            if (event.srcExtension === '.component') {
                //get the filename (we will use this as the component name)
                const componentName = path.basename(event.srcPath);
                //get the file contents as a string
                const code = event.getFileData().toString();

                //create a new BrsFile to act as the primary .brs script for this file
                const brsFile = event.factory.BrsFile({
                    srcPath: event.srcPath.replace(/\.component$/, '.brs'),
                    destPath: event.destPath.replace(/\.component$/, '.brs')
                });
                //parse the generated brs code
                brsFile.parse(code);
                //add this brs file to the event, which is how you "provide" the file
                event.files.push(brsFile);

                //create an XmlFile which will serve as the SceneGraph component for this file
                const xmlFile = event.fileFactory.XmlFile({
                    srcPath: event.srcPath.replace(/\.component$/, '.xml'),
                    destPath: event.destPath.replace(/\.component$/, '.xml')
                });
                xmlFile.parse(`
                    <component name="${componentName}">
                        <script uri="${event.destPath}" />
                    </component>
                `);
                //add this file to the event, which is how you "provide" the file
                event.files.push(xmlFile);
            }
        }
    } as CompilerPlugin;
}

File Factory​

Your plugin will be written against a specific version of BrighterScript. However, your plugin may be loaded by a different version of brighterscript (either by the brighterscript cli or through an editor like vscode). Running different versions of BrighterScript could cause issues in the file api.

To mitigate this, the provideFile events supply a fileFactory, which exposes the file classes from the runner's brighterscript version. When possible, use the file factories found in event.fileFactory instead of direct class constructors. (i.e. use event.fileFactory.BrsFile instead of new BrsFile()). By using the file factories, this ensures better interoperability between plugins and a wide range of brighterscript versions.

You can see examples of this in the previous code snippets above.

Program changes​

Historically, only .brs, .bs, and .xml files would be present in the Program. As a result of the File API being introduced, now all files included as a result of the bsconfig.json files array will be present in the program. Unhandled files will be loaded as generic AssetFile instances. This may impact plugins that aren't properly guarding against specific file types. Consider this plugin code:

validateFile(event){
    if (isXmlFile(event.file)) {
        // do XmlFile work
    } else {
        // assume it's a BrsFile (bad!)
        // it could now be a .jpeg or .png
    }
}

If a plugin has code like this, it may start failing due to receiving an AssetFile or some plugin-contributed custom file type that it didn't expect. We recommend that plugin authors always guard their code with file-specific conditional checks.

srcPath, destPath, and pkgPath​

The file api introduces a breaking change related to file paths. Previously there were only srcPath and pkgPath. pkgPath historically contained the file path as you would reference it in your project, such as source/main.bs. However, there was no property to represent its final path on device (i.e. source/main.brs).

To mitigate this, and since the file api is already causing a few breaking changes, we decided to change the way file paths work. srcPath remains the same. However, pkgPath has been renamed to destPath to represent the path to the file as it exists in your brighterscript project before transpilation. pkgPath will now represent the final path where the file will reside on-device.

Plugin authors need to refactor their plugins to use file.destPath instead of file.pkgPath. While destPath and pkgPath sometimes have the same value, plugin authors should always assume that the paths are different.

Here's a description of each path property in BrighterScript now that the file api has been released.

  • srcPath - the absolute path to the source file. For example:
    C:\projects\YourRokuApp\source\main.bs" or "/usr/projects/YourRokuApp/source/main.bs"
  • destPath - the path where the file exists within the context of a brightscript project, relative to the root of the package/zip. This the path that brightscript engineers will use in their channel code. This should not containing a leading slash or pkg:/ scheme. For example:
    "source/main.bs"
  • pkgPath - the final path where the file will reside on-device. For example:
    "source/main.brs"

Here's an example file showing all three paths:

{
    //location in source project
    srcPath: "C:/projects/YourRokuApp/source/main.bs",
    //location in brighterscript program
    destPath: "source/main.bs"
    //location on device
    pkgPath: "source/main.brs"
}