Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TinCan
✓ const TinCan = require('tincanjs');
✗ import TinCan from 'tincanjs';
Primarily a CommonJS library for Node.js. Native ESM imports are not directly supported without a bundler, which would typically wrap the CJS module. The `require` pattern exposes the global `TinCan` object.
TinCan
✓ <script src="build/tincan-min.js"></script> // Then access `TinCan` globally
✗ import { TinCan } from 'tincanjs';
For browser usage, the library is typically included via a script tag, which exposes the `TinCan` object globally. There is no named export for `TinCan` in a browser-native ESM context.
LRS
✓ const lrs = new TinCan.LRS({ ... });
✗ import { LRS } from 'tincanjs';
Core classes like `LRS`, `Statement`, `Agent`, `Verb`, `Activity` are exposed as properties of the main `TinCan` object, not as direct named exports.
Demonstrates how to initialize an LRS connection and send a basic xAPI statement, followed by querying statements. Uses environment variables for sensitive LRS credentials.
const TinCan = require('tincanjs');
const lrs = new TinCan.LRS({
endpoint: process.env.LRS_ENDPOINT ?? 'https://cloud.scorm.com/tc/public/', // Example endpoint
username: process.env.LRS_USERNAME ?? 'YOUR_USERNAME',
password: process.env.LRS_PASSWORD ?? 'YOUR_PASSWORD',
version: '1.0.3' // Specify the xAPI version, e.g., '1.0.3'
});
const actor = new TinCan.Agent({
name: 'Test User',
mbox: 'mailto:test.user@example.com'
});
const verb = new TinCan.Verb({
id: 'http://adlnet.gov/expapi/verbs/experienced',
display: { 'en-US': 'experienced' }
});
const activity = new TinCan.Activity({
id: 'http://example.com/activities/tincanjs-test',
definition: {
name: { 'en-US': 'TinCanJS Test Activity' },
description: { 'en-US': 'A test activity for TinCanJS quickstart.' }
}
});
const statement = new TinCan.Statement({
actor: actor,
verb: verb,
object: activity
});
lrs.saveStatement(statement, function (err, xhr) {
if (err) {
console.error('Failed to save statement:', err);
return;
}
console.log('Statement saved successfully with ID:', JSON.parse(xhr.responseText)[0]);
});
// Example of retrieving statements
lrs.queryStatements({}, function (err, result) {
if (err) {
console.error('Failed to query statements:', err);
return;
}
console.log('Queried statements count:', result.statements.length);
});
Debug
Known issues
gotchaThe Node.js environment implementation of TinCanJS has a mandatory dependency on the 'xhr2' package for consistent LRS request APIs. It also does not support synchronous LRS requests due to this underlying dependency.fixEnsure 'xhr2' is installed via `npm install xhr2`. All LRS interactions in Node.js must use asynchronous (callback-based) methods.
affects: >=0.1.0
gotchaSupporting older browser versions (e.g., pre-IE10 or specific legacy Chrome/Firefox/Safari versions) may require polyfills for features like TypedArrays, ArrayBuffer with slice, Blob, and TextDecoder/TextEncoder. The default build includes these, but they can be removed to reduce bundle size if targeting modern browsers exclusively.fixIf encountering compatibility issues in older browsers, verify polyfill inclusion. For modern browser-only deployments, consider rebuilding the library after commenting out unnecessary polyfills in `Gruntfile.js`.
affects: >=0.1.0
breakingVersion 0.34.0 introduced a regression in how configured Content-Type headers were handled for LRS requests, potentially leading to incorrect request headers or LRS rejection. This issue was subsequently fixed in version 0.34.1.fixUpgrade to TinCanJS version 0.34.1 or a later version to resolve the Content-Type header regression issue.
affects: =0.34.0
gotchaPrior to version 0.41.1, LRS objects instantiated without an explicit version property could experience issues when querying statements, particularly when dealing with newer xAPI versions like '1.0.2', due to missing compatibility table entries.fixExplicitly set the `version` property in the `TinCan.LRS` constructor (e.g., `version: '1.0.3'`). Alternatively, upgrade to version 0.41.1 or higher, which includes improved default version handling for '1.0.2'.
affects: >=0.1.0, <0.41.1
gotchaThe build system was converted to Grunt in version 0.30.0, and the minifier was upgraded. This change, while not intended to alter interfaces or fix bugs, carried a risk of subtle behavioral differences in the minified files, necessitating thorough testing if upgrading from pre-0.30.0 versions and using minified builds.fixCarefully test minified builds after upgrading from versions older than 0.30.0. If discrepancies are observed, compare minified and unminified versions or consider using the unminified library.
affects: >=0.30.0, <0.31.0
Errors
Common errors & fixes
ReferenceError: TinCan is not defined
The TinCanJS library script was not successfully loaded in the browser environment, or the global `TinCan` object was accessed before the script fully executed.
fixEnsure `<script src="build/tincan-min.js"></script>` is included in your HTML document before any code attempts to use `TinCan`, typically at the end of the `<body>` tag.
Error: Cannot find module 'xhr2'
The `xhr2` npm package, which is a required peer dependency for TinCanJS to function in Node.js environments, is not installed.
fixInstall the `xhr2` module by running `npm install xhr2` in your project's root directory.
TypeError: TinCan.LRS is not a constructor
This error typically occurs when trying to instantiate `LRS` or other core objects before `TinCan` has been properly loaded and assigned, or if attempting to use ES Module import syntax (e.g., `import { LRS } from 'tincanjs'`) which is not supported by this library.
fixFor Node.js, ensure `const TinCan = require('tincanjs');` is at the top of your file. For browsers, verify the `<script>` tag loading `tincanjs` is present and executed. Always access constructors as properties of the `TinCan` object, e.g., `new TinCan.LRS(...)`. Access to XMLHttpRequest at '...' from origin '...' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
The Learning Record Store (LRS) endpoint you are attempting to connect to does not have the necessary Cross-Origin Resource Sharing (CORS) headers configured to allow requests from your web application's origin.
fixThis is an LRS server-side configuration issue, not a client-side library problem. Contact your LRS administrator to ensure that appropriate 'Access-Control-Allow-Origin' headers are configured on the LRS to permit requests from your application's domain.
Audit
Dependencies
xhr2requiredRequired for consistent LRS request API in Node.js environments, providing XHR capabilities.