adapt-project

Node.js library for managing Adapt Learning Framework projects — plugins, schemas, course data, and translations.

Installation

npm install adapt-project

Overview

adapt-project provides a programmatic API for working with Adapt Framework project directories. It handles:

• Course data — Load and manage multilingual content structured as hierarchical JSON (course > menu/page > article > block > component)
• Schemas — Discover and validate content models using JSON schemas from plugins
• Plugins — Discover installed plugins from the src/ directory and read their metadata
• Translations — Export translatable strings and import translated content (CSV, JSON, XLIFF)

Quick Start

const { Framework } = require('adapt-project');

const framework = new Framework({
  rootPath: '/path/to/adapt-project'
}).load();

// Load course data
const data = framework.getData();
data.languages.forEach(lang => {
  const course = lang.getCourseFileItem();
  console.log(`${lang.name}: ${course.item._id}`);
});

// Load schemas
const schemas = framework.getSchemas();

// Discover plugins
const plugins = framework.getPlugins();

// Export translations
const translate = framework.getTranslate({
  masterLang: 'en',
  format: 'csv'
});
await translate.export();

API

Framework

Main entry point representing an Adapt Framework root directory.

const framework = new Framework({
  rootPath: process.cwd(),   // Project root
  outputPath: './build/',    // Build output directory
  sourcePath: './src/',      // Source code directory
  courseDir: 'course',       // Course data subdirectory name
  jsonext: 'json',           // JSON file extension (json or txt)
  trackingIdType: 'block',   // Content type to assign tracking IDs to
  useOutputData: false,      // Read from build output instead of source
  includedFilter: () => true,// Plugin filter function
  log: console.log,
  warn: console.warn
}).load();

Method	Returns	Description
load()	Framework	Load the project's package.json
getData()	Data	Get course data instance
getPlugins()	Plugins	Discover and load all plugins
getSchemas()	Schemas	Load all plugin schemas
getTranslate(options)	Translate	Get translation import/export instance
makeIncludeFilter()	function	Build a plugin filter from config.json build includes/excludes
applyGlobalsDefaults()	Framework	Apply schema defaults to _globals in course data
applyScreenSizeDefaults()	Framework	Apply schema defaults to screenSize in config

Data

Manages the course/ folder — config, languages, and all content items.

Method	Returns	Description
load()	Data	Scan and load all language directories
getLanguage(name)	Language	Get a specific language by folder name
getConfigFileItem()	JSONFileItem	Get the config.json file item
copyLanguage(from, to)	Language	Duplicate a language folder
checkIds()	Data	Validate _id / _parentId structure across all languages
addTrackingIds()	Data	Auto-assign sequential _trackingId values
removeTrackingIds()	Data	Strip _trackingId from all items
save()	Data	Persist all changes to disk

Translate

Export and import translatable strings identified by schema annotations.

const translate = framework.getTranslate({
  masterLang: 'en',
  targetLang: 'fr',
  format: 'csv',         // 'csv', 'json', or 'xlf'
  csvDelimiter: ',',
  shouldReplaceExisting: false
});

await translate.export();  // Export master language strings
await translate.import();  // Import translated strings into target language

Supported formats:

• CSV — One file per content type, with auto-detected encoding and delimiter
• JSON — Single export.json with all translatable strings
• XLIFF 1.2 — Single source.xlf file

Content Hierarchy

Adapt course content follows this structure:

course/
  config.json          — Global configuration
  en/                  — Language folder
    course.json        — Course metadata and _globals
    contentObjects.json — Menus and pages
    articles.json      — Articles within pages
    blocks.json        — Blocks within articles
    components.json    — Components within blocks

Each content item has:

• _id — Unique identifier
• _type — Model type (course, menu, page, article, block, component)
• _parentId — Reference to parent item
• _trackingId — Sequential tracking identifier (auto-generated)

Directory Layout

adapt-project/
  index.js               — Module exports
  lib/
    Framework.js         — Main entry point
    Data.js              — Course data management
    Schemas.js           — Schema discovery and validation
    Plugins.js           — Plugin discovery
    Translate.js         — Translation export/import
    JSONFile.js          — JSON file I/O
    JSONFileItem.js      — JSON sub-item wrapper
    data/
      Language.js        — Single language folder
      LanguageFile.js    — Single language file
    plugins/
      Plugin.js          — Plugin representation
    schema/
      Schema.js          — Base schema class
      GlobalsSchema.js   — Global config schema
      ModelSchema.js     — Content model schema
      ExtensionSchema.js — Model extension schema
      ModelSchemas.js    — Schema collection

License

GPL-3.0