create-digitaltwin

TypeScript CLI tool to create Digital Twin applications with digitaltwin-core.

Features

- Interactive Setup - Guided prompts for project configuration
- Database Support - SQLite (dev) and PostgreSQL (prod) options
- Storage Options - Local filesystem or OVH Object Storage
- Queue Management - Redis support for production workloads
- Docker Ready - Optional Docker and docker-compose configuration
- Example Components - Pre-built IoT sensor collector and data processor
- TypeScript First - Full TypeScript support with strict typing
- CLI Integration - Includes digitaltwin-cli for component generation

Quick Start

$3

``bash
npm init digitaltwin my-digital-twin
cd my-digital-twin
npm install
npm run dev
`

$3

`bash
npx create-digitaltwin my-digital-twin
cd my-digital-twin
npm install
npm run dev
`

$3

`bash
yarn create digitaltwin my-digital-twin
cd my-digital-twin
yarn install
yarn dev
`

$3

`bash
npm install -g create-digitaltwin
create-digitaltwin my-digital-twin
`

Usage

$3

`bash
create-digitaltwin [project-name]
`

The CLI will guide you through configuration options:

> Note: You can use npm init digitaltwin as a shorthand for npx create-digitaltwin thanks to npm's init command aliasing.

- Project Name: Name for your Digital Twin application
- Database: SQLite (file-based) or PostgreSQL (production-ready)
- Storage: Local filesystem or OVH Object Storage (S3-compatible)
- Redis: Enable for distributed queue management
- Docker: Include Docker configuration files
- Examples: Include sample IoT components

$3

Use the --yes flag to skip prompts and use defaults or CLI options:

`bash


Create with all defaults

npx create-digitaltwin my-app --yes

Create with PostgreSQL and Redis

npx create-digitaltwin my-app --yes --database postgresql --redis

Create with Docker, no examples, skip install

npx create-digitaltwin my-app --yes --docker --no-examples --skip-install

Full example with all options

npx create-digitaltwin my-app --yes \
--database postgresql \
--storage local \
--storage-path ./data \
--redis \
--docker \
--examples
`

$3

| Option | Description | Default |
|--------|-------------|---------|
| -y, --yes | Skip prompts, use defaults | false |
| --database | Database: sqlite or postgresql | sqlite |
| --storage | Storage: local or ovh | local |
| --storage-path | Local storage directory | ./uploads |
| --redis | Enable Redis for queues | true |
| --docker | Include Docker files | false |
| --examples | Include example components | true |
| --no-examples | Skip example components | - |
| --skip-install | Skip npm install | false |

Generated Project Structure

`
my-digital-twin/
├── src/
│ ├── index.ts # Main application entry
│ └── components/ # Example components (optional)
│ ├── jsonplaceholder_collector.ts
│ └── index.ts
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
├── .env # Environment variables template
├── .gitignore
├── README.md # Project-specific documentation
├── dt.js # CLI wrapper for digitaltwin-cli
├── Dockerfile # Docker configuration (optional)
├── docker-compose.yml # Multi-service setup (optional)
└── dist/ # Compiled JavaScript (after build)
`

Example Components

When enabled, the generator includes working example components:

$3

- Fetches real data from the JSONPlaceholder API (posts and users)
- Runs every 15 seconds to demonstrate scheduled data collection
- Includes error handling and performance metrics
- Shows how to integrate with external REST APIs
- Stores collected data with metadata in your configured storage

Generated Endpoints:
- GET /api/jsonplaceholder - Latest collected data from JSONPlaceholder

CLI Integration

Each generated project includes dt.js, a wrapper that calls digitaltwin-cli for component generation:

`bash


Generate components after project creation


node dt make:collector WeatherCollector --description "Collects weather data"
node dt make:handler ApiHandler --method post
node dt make:harvester DataProcessor --source weather-collector
node dt make:assets-manager ImageManager --content-type "image/jpeg"
`

This provides seamless component scaffolding within your Digital Twin project.

Development

$3

`bash
git clone
cd create-digitaltwin
npm install
npm run build
npm link
`

$3


`bash
npm run dev my-test-project
`

$3

- npm run build - Compile TypeScript to JavaScript
- npm run dev - Run in development mode with tsx
- npm test - Run tests with Japa
- npm start - Run compiled CLI
- npm run prepare - Pre-publish build hook

Testing

The CLI uses the Japa testing framework. Tests cover:
- Project generation with various configurations
- Non-interactive mode with CLI options
- Input validation

`bash
npm test
`

Digital Twin Architecture

Projects generated by this CLI follow the digitaltwin-core architecture:

- Collectors: Fetch data from external sources on schedules
- Harvesters: Process and transform collected data
- Handlers: Expose HTTP endpoints for real-time operations
- Assets Managers: Manage file uploads with metadata
- Engine: Orchestrates all components with Redis queues

Environment Configuration

Generated projects include comprehensive environment validation:

`typescript
// Automatic validation of required environment variables
const env = Env.validate({
PORT: Env.schema.number({ optional: true }),
DB_HOST: Env.schema.string(),
STORAGE_PATH: Env.schema.string({ optional: true }),
// ... more validations based on your choices
})
``

TypeScript Support

This CLI is built with TypeScript and generates fully-typed projects:

- Strict typing for all configuration objects
- Interface definitions for sensor data and processing results
- Type-safe environment variable validation
- IDE support with full IntelliSense

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure TypeScript compilation passes
5. Submit a pull request

Related Projects

- digitaltwin-core - Core framework
- digitaltwin-cli - Component generation CLI
- Digital Twin Examples - Sample implementations

License

MIT © Hoffmann Axel