Getting started in 5 minutes

No clone required

This guide uses npm only. You do not need the LessonKit GitHub monorepo unless you are contributing or running examples.

LMS export is a separate guide

This page covers local preview in about five minutes. SCORM packaging, bridge configuration, and env setup are in LMS Go-Live (single canonical guide). Appendix shortcuts: First LMS export · Ship to LMS checklist · Production checklist.

Prerequisites: See Prerequisites. Node.js 20.19+ recommended for npx @lessonkit/cli init (Vite 8).

You are here — golden path

  [1] Local preview          [2] Build smoke           [3] LMS Go-Live (required)
       npm run dev      →    npm run build       →     bridge + env + package + upload
       ◄── you start here     optional smoke only       do not skip before LMS upload

Step	Status on this page	Next
1. Preview	Sections 1–3 below	Keep using npm run dev while editing
2. Build smoke	Section 4 (optional)	Confirms Vite production build only—not LMS-ready
3. LMS Go-Live	Not on this page	LMS Go-Live — required before upload

1. Create a project

npx @lessonkit/cli init my-course
cd my-course

init runs npm install by default and writes lessonkit.json, src/courseConfig.ts, and a starter src/App.tsx.

Advanced init flags

Flag	When to use
lessonkit init --here	Scaffold in the current directory (must be empty or dotfiles-only without --force)
lessonkit init my-course --skip-install	Create files only; run npm install yourself after fixing Node/proxy issues
lessonkit init --here --force	Scaffold in a non-empty directory; conflicting template files are backed up to .lessonkit-init-backup/ before overwrite

See CLI reference for all options.

2. Preview locally

Dev preview ≠ LMS upload

npm run dev uses console telemetry sinks in the init template. A successful npm run build does not mean the course is ready for LMS upload—production mode requires bridge config, env proxies, or temporarily disabled tracking/xAPI. Follow LMS Go-Live before packaging.

npm run dev

Open the URL Vite prints (usually http://localhost:5173). The starter template uses console telemetry sinks in development.

Success check: You should see a scenario paragraph and a quiz with two choices. Open the browser console — when you answer the quiz, you should see telemetry events such as quiz_answered.

Alternative: npx lessonkit dev (same as the dev script).

3. Change one quiz

Edit React and lessonkit.json together

Packaging validates that courseId, lessonId, and every checkId in React appear in lessonkit.json. Change both files in the same edit—mismatches are the most common lessonkit package failure. See Keep React IDs in sync.

After saving both files and refreshing the browser, you should see your new question text and be able to submit the quiz.

Before — src/App.tsx (excerpt):

<Quiz
  checkId="ready-to-build"
  question="Ready to build?"
  choices={["Not yet", "Yes"]}
  answer="Yes"
/>

After:

<Quiz
  checkId="ready-to-build"
  question="What is the first step when you receive a suspicious email?"
  choices={["Open the attachment", "Verify the sender"]}
  answer="Verify the sender"
/>

Matching lessonkit.json entry under course.assessments[]:

{
  "checkId": "ready-to-build",
  "question": "What is the first step when you receive a suspicious email?",
  "choices": ["Open the attachment", "Verify the sender"],
  "answer": "Verify the sender",
  "passingScore": 1
}

Keep checkId unchanged when you edit question text only. When you add lessons or checks, update both React and the manifest in the same commit.

4. Production build (optional smoke test)

npm run build

Output goes to dist/ (Vite SPA).

Do not preview the production bundle yet

npm run build succeeds without env vars, but vite preview or opening dist/ directly will throw in production mode unless you add .env proxy URLs or disable tracking/xAPI. Keep iterating with npm run dev. See LMS Go-Live before uploading to an LMS.

Next steps

• LMS Go-Live — start here for smoke test vs production (single canonical guide)

• Quickstart — add LessonKit to an existing Vite app

• Block cookbook — per-block React + manifest examples

• FAQ — common questions

• Live examples — full demo courses (Read the Docs embeds; no clone required)