The easiest way to get started with a track is by using the provided Lightrail Track Starter (opens in a new tab). Lightrail development requires a functioning install of
npm. Assuming you have a recent version of
npm available on your system, just
cd to the directory you'd like to create your project in, then run this command to fetch the starter from the lightrail repository:
npx gitget lightrail-ai/lightrail/tracks/starter your_project_name
cd into your newly created project directory, and run
npm install to install required dependencies.
Having done this, you'll be presented with roughly the following project structure (plus a few files we can ignore for now, like
track-distis the output directory for your bundled, minified track. Don't put anything in it yourself; it'll be filled by the build process for your track.
package.jsonshould be familiar from other Node projects; edit the name to the desired track name (or a derivative of the track name, e.g.
lightrail-...-track— it doesn't need to match exactly). You can also see the scripts defined in here—the important ones are
npm run build(to build the output files in track-dist, for distribution) and
npm run dev(which just runs
buildwith file-watchers, to rebuild on changes).
index.tsis the focal point; this is where your track gets defined. Of course, you can define functionality across other files, and simply import it here, but the final track definition must be the default export of
index.ts. The starter project contains a mostly-empty placeholder here; The next section of the documentation goes into detail on how to implement your desired functionality within that structure.
Currently, the development workflow for Lightrail tracks is a bit rough around the edges; better tooling / workflows are coming soon. For now, follow these steps to test your track locally and iterate:
Find the track directory for your installation of Lightrail. To locate this from within the Lightrail application, click the gear icon in the main prompt input and make sure the
Trackssection of the configuration UX is open. Near the top of the section, the path to your tracks directory should be visible; for example, on Fedora, it should be something like
Make a symlink in this directory that points to your track's folder. For example, if your track is defined in my Documents folder, you might run something like this:
ln -s /home/yourusername/Documents/your_project_name /home/yourusername/.config/lightrail-core/tracks/your_project_name
Make sure to replace both paths with the appropriate ones for your system!
From your track directory, run
npm run dev
Relaunch Lightrail, and your track should be active in your Lightrail installation. To view logs from your track (or from the Lightrail system), make sure to run Lightrail from the command-line. Whenever you make changes to your track, they'll automatically be built into the appropriate format for Lightrail; just relaunch Lightrail and you'll see the updates (Hot-reloading of tracks coming soon).