setup-data-project

Set up a TypeScript data analysis project with Node.js or Bun. Generated development commands use the selected runtime.

The library is maintained by Nael Shiab, computational journalist and senior data producer for CBC News.

Tip

To learn how to use these libraries and more, check out Code Like a Journalist, a free and open-source data analysis and data visualization course in TypeScript.

# Node
npx @nshiab/setup-data-project

# Bun
bunx --bun @nshiab/setup-data-project

The CLI uses the runtime that launches it. Its executable has a Node shebang, so use bunx --bun to explicitly run it with Bun.

Select libraries interactively, or combine library flags to install without prompts:

npx @nshiab/setup-data-project --sda
npx @nshiab/setup-data-project --format --geo --dataviz
bunx --bun @nshiab/setup-data-project --sda-core --ai

Available library flags:

• --sda: simple-data-analysis
• --sda-core: simple-data-analysis-core
• --ai: journalism-ai
• --google: journalism-google
• --web-scraping: journalism-web-scraping
• --finance: journalism-finance
• --format: journalism-format
• --climate: journalism-climate
• --dataviz: journalism-dataviz
• --geo: journalism-geo
• --statistics: journalism-statistics
• --web: journalism-web
• --extras: journalism-extras

Run --help for usage. Library flags keep existing dependency versions and cannot be combined with --docs.

The project includes sda/main.ts, helpers, tests, data and output folders, .env, .gitignore, and managed sections in README.md and AGENTS.md. Existing source files, environment values, scripts, tooling configuration, and unmanaged documentation are preserved.

Generated projects run TypeScript directly with Node or Bun. Vite+ provides formatting, linting, type checking, and Vitest tests. Use npm run sda, npm run all-tests, and npm run fix (or bun run for Bun projects). The generated all-tests command also succeeds when no tests exist. New development tools are installed at their latest versions; existing dependencies are preserved.

For test-driven development, run one test file and watch for changes (replace the example path with your test file):

npx vp test sda/tests/example.test.ts --watch
# Bun
bun run --bun vp test sda/tests/example.test.ts --watch

VS Code configuration recommends the Vite+ extension pack and enables formatting, lint fixes on save, and visual line wrapping. Existing .vscode/extensions.json and .vscode/settings.json files are left unchanged.

Documentation is downloaded automatically for the exact installed library versions. Each library's release archive preserves its README, license, llms.txt index, granular API pages, and media under docs/<library>/. Observable Plot downloads one version-matched cached reference (or falls back to upstream sources), then splits it into feature, mark, and transform pages with an index at docs/observable-plot/llms.txt. Website controls are removed; examples that depend on upstream setup or interactive templates are labeled. The generated docs/ folder is ignored by Git.

After cloning or changing dependencies, run npm run docs or bun run docs. You can also refresh documentation directly:

npx @nshiab/setup-data-project --docs
bunx --bun @nshiab/setup-data-project --docs

--docs requires installed dependencies and only refreshes documentation. It runs no prompts or installs and leaves project configuration unchanged. Failed downloads preserve previous files, warn that they may be stale, and exit unsuccessfully. Generated docs scripts pin the setup CLI version that created them. Use --help for usage.

For development, use npm ci and npm run all-tests. npx vp pack produces the npm executable. Releases use npm run patch, npm run minor, or npm run major from main; GitHub Actions publishes to npm.

To cache documentation for the latest Observable Plot version, run:

npm run cache-plot-docs

This checks npm and skips generation if that version is already cached. To generate or refresh a specific version, run npm run cache-plot-docs -- 0.6.17. Review and commit docs-cache/observable-plot/<version>/llm.md; keep earlier versions for pinned projects. The command fetches the tagged upstream pages and license.