This is a very simple template for creating NodeCG bundles using TypeScript. This features using WebPack to "bundle" (pun mildly intended) all code for the extension, dashboard panels and graphics into a single script file.
NodeCG is a system that allows you to make broadcast graphics using Node.JS, allowing you to leverage readily available technologies to generate graphics for live broadcasts, live streams, and so on. Historically something like this would require expensive, dedicated equipment; NodeCG leverages the display capabilities of web technology to allow you to create real time graphics with off the shelf tools.
In a nutshell, NodeCG allows you to easily synchronize code running on a server, a user facing dashboard and web pages displaying their content live (e.g. a browser source in OBS) by allowing all parts to seamless communicate with each other across the server, client and stream boundary.
In order to use this template, you need a running instance of NodeCG. This section assumes that you're new to this and walks you through the entire process. If you're already familiar with NodeCG you can skip to the next section. Similarly, if you already have a running NodeCG instance, you can skip that setup step.
NodeCG is a complete web application that
will be running its own web server; the first step is to install it. This guide
will be installing via git
; there is also a nodecli
script available as
well, but this guide does not cover that.
cd somelocation
to go to the location you want to installNodeCG
ingit clone https://github.com/nodecg/nodecg.git
to clone the repositorycg nodecg
andgit checkout v1.8.1
; this step checks out the specific tagged version you would like to run. As of the time of this writing,1.8.1
is the latest version, but there may be a newer one available.npm init
to download all packages and getNodeCG
ready to run.
NodeCG
works on the concept of bundles
, which are special node
packages
that contain functionality in the form of an extension
, panels
and
graphics
that communicate with each other to allow you to create and control
the display of live graphics.
-
cd bundles
to go into thenodecg
bundles directory -
git clone https://github.com/OdatNurd/nodecg-ts-template.git my-bundle
to clone the repository and put the bundle in place; choose any name you like for this. -
cd my-bundle
to go into the bundle, thenyarn init
andyarn build
to download the appropriate packages and runwebpack
to build all of the code out.NOTE: I use
yarn
instead ofnpm
, which is why there is ayarn.lock
file present. You can remove that and usenpm
if you prefer.
At this point, extension.js
should be created, which contains the code that
will run on the server side, while dashboard/script/
and graphics/script/
will contain the code that runs in the dashboard panel and graphic respectively.
To verify that everything works, we can fire up our NodeCG
instance and see
things in action.
-
cd ../..
to go back to thenodecg
installation folder -
node index.js
will start the server running. You should see something like the following; the[my-bundle]
log line is visible in the code in theextension
.[nodecg] No config found, using defaults. info: [nodecg/lib/server] Starting NodeCG 1.8.1 (Running on Node.js v14.15.4) info: [my-bundle] ==> Extension started info: [nodecg/lib/server/extensions] Mounted my-bundle extension info: [nodecg/lib/server] NodeCG running on http://localhost:9090
-
Open a browser on http://localhost:9090, which will show you the NodeCG dashboard, where you should see a panel with a simple form in it.
-
Check the browser console; you should see a log indicating that the dashboard panel loaded; the code for this log line is visible in the code in the
panel
. -
Click the button
Transmit a sample message
; the browser console should log that a message was transmitted, and you should see it being received by the server:info: [template] Received msg: I am a sample message
-
At the top right of the screen, click on
graphics
to view the graphics available from this bundle. You should see a single graphic namedoverlay/index.html
with a0
next to it; this is the number of copies of this graphic that are currently loaded. Click the link to open the graphic. -
Check the browser console; you should see a log indicating that the graphic
overlay
has loaded; the code for this is in theoverlay
. -
In the dashboard, there should now be a
1
next tooverlay.html
; there is now one copy of it loaded and connected to the server. -
Click on
workspace
to go back to the dashboard; enter some text in the field and clickDisplay
-
In the loaded
graphic
, the text is now visible in a banner across the top of the screen.
In NodeCG, functionality is "slotted in" in the form of a Bundle
; this is a
NodeJS package containing an extension
, one or more panels
and one or more
graphics
. Bundles are installed into a NodeCG instance, allowing you to
easily mix and match functionality.
Each of the three parts of the bundle; extension
, panel
and graphic
are
connected together internally by NodeCG, and via the API they can
intercommunicate with each other,
Each NodeCG bundle contains exactly one extension
, which is code that runs on
the back end server directly inside of a running instance of NodeCG. This takes
the form of either a file named extension.js
in the root of the bundle, or a
folder named extension
which contains (at a minimum) an index.js
file/
When the bundle is mounted, NodeCG will import either of those two files and
expect them to export a single function which kicks off the functionality of
the server side of the bundle (if any). The function is invoked with a single
parameter of nodecg
which provides access to the NodeCG API.
A NodeCG bundle can contain any number of panels
; these are web pages that
will appear in the NodeCG dashboard for you to interact with. Each is rendered
inside of an iframe
to keep each one self contained.
Inside of the panel, a global nodecg
object is available to allow access to
the client side portion of the NodeCG API.
A NodeCG bundle can contain any number of graphics
(though usually at least
one); these are web pages that are overlaid on the eventual broadcast source
(e.g. loaded in a Browser source in OBS).
Like a panel
, a graphic
has access to a global nodecg
object to allow
access to the NodeCG API.
Each of the three parts of NodeCG
; extension
, panel
and graphic
have
access to the NodeCG API. One of the things this allows is transmitting a
message to other interested parties. This can be done in any of these places,
and the message will be delivered to anyone that's listening.
In the example above, a message
is used to transmit something from the
dashboard panel
to the extension
running on the server. Here the text is
simply displayed, but this could also trigger some action or request for data
which could be later returned via a different message.
Remember; the graphic can also transmit and receive messages as well, so this mechanism can be used to communicate information to and from graphic, allowing you to control what it displays.
A Replicant
is an object that can be constructed via the NodeCG
API and
makes it easy to synchronize information between the extension
, panels
and
graphics
.
In use, you construct a Replicant
giving it a specific name; you would do
this in at least two places (e.g. in a panel
and in a graphic
). Whenever
the value of a Replicant
changes, NodeCG
automagically synchronizes the new
value with all other instances of Replicant
with the same name.
In the example above, a Replicant is used to tell the graphic
to display the
text entered in the panel
; when you click the button, the code in the panel
updates the value of the Replicant
, and the graphic
is immediately receives
an update.
This is similar to using a message
, but much easier for cases when the
information being transmitted is going to be used directly for display.