Skip to main content
What this page covers: how to configure learn.json for authors. Set editor mode and agent, control authentication and assessment, choose grading, define paths, and enable delivery. Includes examples for Gitpod and Codespaces. ✅

​
The learn.json

The learn.json file is where all teacher-side configuration lives. You can change the following properties:
Note: Properties marked as optional in your project may be inferred by LearnPack based on the exercises.
  • port: The port where the instructions will be hosted. Default: 3000.
  • authentication: Object with authentication options.
    • mandatory: If true, the user must log in before starting.
  {
    "authentication": {
      "mandatory": true
    }
  }
  • assessment: Object with assessment options.
    • maxQuizRetries: Maximum quiz retries. Default: 3.
    {
  "assessment": {
    "maxQuizRetries": 3
  }
}
  • editor: Object with editor options.
    • mode: "extension" (VS Code plugin) or "preview" (local without VS Code).
    • agent: Where instructions render: "vscode" or "os".
    • version: UI version. Defaults to latest. Example "5.0" uses the latest 5.0.x.
    {
  "editor": {
    "mode": "extension",
    "agent": "vscode",
    "version": "5.0"
  }
}
  • dirPath: Path to the configuration directory. Default: .learn at repo root.
  • configPath: Path to the configuration file. Default: learn.json.
  • outputPath: Path to the compiled output. Default: .learn/dist.
  • publicPath: Public path where the result is hosted. Default: /preview.
  • publicUrl: URL where the instructions will be hosted. Depends on the agent.
  • grading: Grading mode for the tutorial. See Grading LearnPack Tutorials.
  • exercisesPath: Path to the folder with the exercises. Often the repo root.
  • disabledActions: Array of actions to disable (Build, Reset, Test, Tutorial).
  • slug: The tutorial name. Auto-generated, but can be changed.
  • title: The tutorial title. Use descriptive, SEO-friendly wording. 
    {
  "title": {
    "es": "Un titulo corto en español",
    "en": "Short title in english"
  }
}
  • preview: Image URL for the tutorial introduction.
  • repository: Link to the tutorial repository.
  • description: Multilingual description of the tutorial. Include topics, technologies, and learner outcomes. 
    {
  "description": {
    "es": "Descripcion en español",
    "en": "English description"
  }
}
  • duration: Estimated time to finish the tutorial.
  • difficulty: One of easy, beginner, intermediate, hard.
  • projectType: "tutorial" or "project". Interactive packages are “tutorials”.
  • autoPlay: If true, LearnPack starts automatically in VS Code.
  • video: Intro video URLs per language. 
    {
  "video": {
    "intro": {
      "es": "www.example.url",
      "en": "www.example_video.url"
    }
  }
}
  • bugs: URL to report bugs found in the tutorial.
  • webpackTemplate: Custom webpack template for your tutorial.

​
Delivery configuration

Use delivery to enforce a specific submission method: 
{
  "delivery": {
    "instructions": {
      "us": "Paste the URL of the Google Sheets template with the different strategies discussed during the game",
      "es": "Agrega el URL al document de Google Sheets con las diferentes strategies discutidas"
    },
    "formats": ["url"],
    "regex": "https://docs.google.com/"
  }
}

​
Delivering a flag as project submission

Some projects use a CTF-style flag: 
{
  "delivery": {
    "instructions": {
      "us": "Paste the flag you found using the format FLAG{hash}",
      "es": "Agrega la bandera que encontraste usando el formato FLAG{hash}"
    },
    "formats": ["flags"],
    "quantity": 1
  }
}
Tip: If a student must collect more than one flag, increase quantity. The system ensures all are submitted.

​
Editor options at a glance

SettingValuesWhere it opensWhen to use
editor.modeextension, previewVS Code extension or local previewMatch your development flow.
editor.agentvscode, osVS Code or browserKeep agent consistent with your environment.
editor.versione.g. 5.0Latest 5.0.x UIPin a major.minor if needed.
Heads-up: If LearnPack detects a different agent than the one suggested in learn.json, it shows a warning to preserve the best experience.

​
Compiler plugins

LearnPack supports python, javascript, html, css, dom, react via plugins: Install a plugin: 
learnpack plugins:install <name-of-plugin>
Example: 
learnpack plugins:install @learnpack/html
Good to know: LearnPack can auto-install the required plugin based on your exercises. 👀

​
Cloud provisioning

LearnPack does not install tech stacks for your tutorials. Use Gitpod or GitHub Codespaces to remove setup and minimize friction. Provisioning vendors can prepare the environment, then LearnPack starts immediately.

​
Provisioning with Gitpod

Gitpod uses a root-level .gitpod.yml:
Define Docker image, language versions, and any tools your tutorial needs.

​
Provisioning with GitHub Codespaces

Codespaces provides a customizable cloud dev environment. Preconfigure dependencies and tools so learners can start fast. Example: .devcontainer/devcontainers.json 
{
  "name": "Node.js",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:0-18",
  "customizations": {
    "vscode": {
      "settings": {
        "editor.defaultFormatter": "esbenp.prettier-vscode",
        "workbench.editorAssociations": {
          "*.md": "vscode.markdown.preview.editor"
        }
      },
      "extensions": ["learn-pack.learnpack-vscode"]
    }
  },
  "onCreateCommand": "npm i [email protected] -g && npm i @learnpack/[email protected] -g && learnpack plugins:install @learnpack/[email protected] && learnpack plugins:install @learnpack/[email protected]"
}

​
Next up

​
See also