cazala/synaptic: an architecture-free neural network library for JavaScript

What Synaptic is for, and who actually needs it

Synaptic is a JavaScript neural network library that runs in node.js and in the browser. Its distinguishing claim is that the generalized algorithm is architecture-free: you are not limited to a fixed topology, and the README says you can build and train "basically any type of first order or even second order neural network" architecture. The algorithm comes from Derek D. Monner's paper on a generalized LSTM-like training algorithm for second-order recurrent neural networks, and the source code carries comments referring back to equations in that paper.

The intended audience is people who want to assemble a network themselves and watch it learn. Synaptic ships built-in architectures: multilayer perceptrons, multilayer long short-term memory networks, liquid state machines and Hopfield networks. It also ships a trainer with built-in tasks such as solving an XOR, a Distracted Sequence Recall task and an Embedded Reber Grammar test, so you can compare how different architectures behave on the same problem. That combination of hand-wiring plus ready-made benchmarks is the reason to pick it over a library that hides the graph behind a declarative model definition.

It is not a deep learning framework. There is no mention of GPU execution, distributed training, or automatic differentiation over a tensor graph. If your work is training a large model on a large dataset, this library is the wrong shape entirely.

How the neuron, layer and gate model fits together

The object model is small and explicit. A Neuron is the unit, a Layer holds neurons, a Network holds layers, and connections between layers are created by projecting one layer onto another. A projection returns a Connection object, and that object is what gates act on. The README's LSTM example shows the pattern: the input layer projects into the memory cell, the memory cell projects back into itself for the self-connection, and the memory cell also projects into the input, forget and output gates to form peephole connections.

Gating is the part worth understanding before you write anything. A gate layer does not just receive signals; it multiplies the connection it is attached to. The README calls Layer.gate with a gateType: Layer.gateType.INPUT for the connection from the input layer into the memory cell, Layer.gateType.ONE_TO_ONE for the self-connection, and Layer.gateType.OUTPUT for the connection from the memory cell to the output layer. That single API is what lets the same base classes express a plain perceptron and an LSTM with peepholes, without the library knowing in advance which one you are building.

Networks are assembled by calling this.set with input, hidden and output keys, where hidden is an array of layers. That is the whole architecture contract. Nothing infers shape from your data, and nothing validates that your wiring makes sense, which means a mis-projected layer fails at training time rather than at construction time.

Installing Synaptic and training a perceptron on XOR

In node, the README gives a single npm command. The package's main entry is ./dist/synaptic, so the require resolves against the prebuilt bundle rather than src/.

npm install synaptic --save

In the browser, the README offers bower or a CDN script tag pinned to version 1.1.4 on cdnjs.

<script src="https://cdnjs.cloudflare.com/ajax/libs/synaptic/1.1.4/synaptic.js"></script>

Once installed, the README's usage block pulls the five constructors off the module. The require line is not needed in the browser.

var synaptic = require('synaptic');
var Neuron = synaptic.Neuron,
	Layer = synaptic.Layer,
	Network = synaptic.Network,
	Trainer = synaptic.Trainer,
	Architect = synaptic.Architect;

A first real use is the perceptron the README builds: two input neurons, three hidden, one output, with the input layer projected onto the hidden layer and the hidden layer projected onto the output layer. You extend Network by assigning the constructor to the prototype, then instantiate it and hand it to a Trainer. The README's own run of myTrainer.XOR() is reported as an error of about 0.004998819355993572 over 21871 iterations in 356 time units, and the subsequent activate calls return values near 0.02 and near 0.98 for the four XOR inputs. Treat those as the README's illustrative numbers, not as a guarantee for your machine.

Where Synaptic breaks down or is the wrong tool

The most concrete limitation is the release history. The newest tagged release is 1.1.4, dated 2017-10-22. The repository is not archived and the last push to master was on 2026-08-01, so work has happened since, but nothing in the repository shows a newer published version. Anyone depending on npm install synaptic is depending on a 2017 artifact, and any fix merged after that date is not in the package you get.

A second constraint is that the architecture-free promise shifts the burden onto you. Nothing in the library tells you that your gate wiring is wrong, that your connection is one-to-one where it should be all-to-all, or that your hidden array is ordered the way you think. The README documents the mechanism but the wiki, not the README, is where Neurons, Layers, Networks, Trainer and Architect are explained in depth. Expect to read the wiki before the API feels predictable.

Finally, the training story is single-process and in JavaScript. The built-in tasks are small by design: XOR, Distracted Sequence Recall, Embedded Reber Grammar. There is no batching story, no GPU path, and no mention of saving or loading trained weights in the README. If your model needs to be checkpointed, served under load, or trained on more than toy data, Synaptic is the wrong tool and a tensor-based framework is the right one.

How Synaptic differs from Brain.js and TensorFlow.js

The closest alternative in the same language and runtime is Brain.js, which also targets JavaScript in node and the browser. The difference is in who owns the graph. Brain.js-style libraries take a network type and a configuration and build the topology for you: you pick a kind of network and hand over data. Synaptic inverts that. You instantiate neurons and layers, project them, and gate the connections yourself, which is why the README can show an LSTM with peepholes written out in full rather than hidden behind a config key. If you want to experiment with a topology that no library ships, Synaptic's model is the one that lets you express it.

TensorFlow.js occupies a different position. It is a tensor computation library with automatic differentiation, and it targets the browser with WebGL acceleration. Synaptic has no tensor abstraction: values flow neuron to neuron through Connection objects. That makes Synaptic easier to read when you are learning what a gate does, and far slower and more awkward when you are doing anything at scale. Choosing between them is really choosing between inspecting the graph and executing it efficiently.

Maintenance cost, build steps and licence status

The build is webpack 3 driven by webpack.config.js, with Babel 6 presets and plugins in devDependencies. That toolchain is old, and the practical consequence is that npm run build may need a Node version compatible with webpack 3. The test scripts are split: npm run test:mocha:src runs mocha against the source with an injection helper, npm run test:mocha:dist runs the same suite against the built bundle, and npm run test:karma:browsers drives Chrome, Firefox and Safari through Karma. There is also a PhantomJS target. The pre-push hook runs test and build together, so a contributor's local setup assumes both work.

Upgrading is the real cost. Because the published version has not moved past 1.1.4, tracking master means building from source yourself and carrying that build. There is no documented migration path in the README, and no changelog is referenced beyond the release tags.

The licence is the other thing to check before shipping. The repository metadata reports the licence as NOASSERTION, meaning the automated classifier could not map the LICENSE file to a known SPDX identifier. The LICENSE file exists at the top level, so read it directly. This is not legal advice, but a licence that does not resolve to a standard identifier is a question for whoever signs off on dependencies at your organisation, particularly if you ship the dist/synaptic bundle to end users.

Editorial conclusion

Adopt Synaptic if you are teaching how a perceptron, LSTM or Hopfield network is wired, or prototyping a small recurrent architecture in the browser where a hand-built graph beats a fixed declarative model. Do not adopt it if you need GPU training, large datasets, or a library with a release cadence: the newest tagged release is 1.1.4 from 2017-10-22, and the last push to master was on 2026-08-01. Before committing, read the Trainer and Architect wiki pages, run npm run test:mocha:src to confirm the source tests pass on your Node version, and check whether the LICENSE file's terms fit how you intend to ship the dist/ bundle.

Frequently asked questions

Official sources

1. cazala/synaptic on GitHub
2. Issues
3. README
4. Releases