From npm scripts

If you drive your project with package.json scripts - npm run build, npm run test, npm run ci - OrchStep replaces npm's script-runner role with a clearer, cross-language workflow. You keep using npm for the actual Node build; OrchStep just orchestrates the steps around it, with no hidden pre/post hooks and a real --dry-run.

The 30-second version

npm run build               ->   orchstep run build
npm run                     ->   orchstep list-tasks
npm run ci                  ->   orchstep run ci
npm run deploy -- --env=prod ->  orchstep run deploy --var environment=prod

How the concepts map

Side by side

{
  "scripts": {
    "clean": "echo cleaning",
    "prebuild": "npm run clean",
    "build": "echo building",
    "test": "echo running tests",
    "ci": "npm run test && npm run build"
  }
}

name: app
desc: Build, test, and deploy the app

defaults:
  version: "1.0.0"
  environment: "staging"

tasks:
  clean:
    steps:
      - name: clean
        func: shell
        do: echo "cleaning"
  build:                      # the implicit prebuild hook becomes an explicit step
    steps:
      - name: run_clean
        task: clean
      - name: compile
        func: shell
        do: echo "building v{{ vars.version }}"
  test:
    steps:
      - name: unit
        func: shell
        do: echo "running tests"
  deploy:
    steps:
      - name: ship
        func: shell
        do: echo "deploying v{{ vars.version }} to {{ vars.environment }}"
  ci:                         # the && chain becomes ordered task calls
    steps:
      - name: run_test
        task: test
      - name: run_build
        task: build

Run it

orchstep run build
orchstep run deploy --var environment=production --var version=2.1.0

$ orchstep run deploy --var environment=production --var version=2.1.0
  $ echo "deploying v2.1.0 to production"
deploying v2.1.0 to production
Result: success

npm's npm run deploy -- --env=prod becomes the explicit --var environment=prod. List everything with orchstep list-tasks.

Gotchas worth knowing

• Pre/post hooks become explicit. npm's implicit prebuild/postbuild hooks run automatically and invisibly; in OrchStep you make them explicit steps (more verbose, but zero hidden magic - see build calling clean above).
• You're replacing the script runner, not npm. Keep using npm run build for the real Node build and call it from a shell step during (and after) the migration - OrchStep orchestrates, npm still builds.
• && chains become ordered steps. A "npm run a && npm run b" script becomes ordered task: steps, so you get per-step status and --dry-run.
• env is reserved. Don't name a variable env - that namespace is for environment variables ({{ env.PATH }}). Use environment (the loader will stop you with a clear error otherwise).

What you gain

• orchstep run --dry-run previews the whole chain (including hooks and ci).
• Hidden pre/post hooks become visible, ordered steps with their own status.
• Steps pass typed outputs instead of echoing strings.
• Shared scripts can become versioned modules.

Where to go next

• Composing Tasks - how task: calls chain steps in order.
• Variables and Outputs - replacing -- --flag with --var.
• CLI Reference - every flag for orchstep run.