Skip to main content

Project Scaffolding

Create new Cardano projects with best practices and ready-to-use templates.

Overview​

Project Scaffolding provides:

  • 7 project templates for different use cases
  • 8 optional features to mix and match
  • Best-practice project structure
  • Pre-configured tooling (TypeScript, ESLint, Jest)
  • Network-specific configuration

Installation​

import {
  scaffold,
  getTemplates,
  getFeatures,
  validateScaffoldConfig,
} from 'cardano-devkit';

Quick Start​

import { scaffold } from 'cardano-devkit';

// Create a new dApp project
const result = await scaffold({
  name: 'my-dapp',
  template: 'dapp',
  features: ['aiken', 'testing', 'devnet'],
});

console.log('Created:', result.projectPath);
console.log('Files:', result.files.length);
console.log('Next steps:', result.nextSteps);

CLI Usage​

# Interactive scaffolding
cardano-devkit new my-project

# With template
cardano-devkit new my-dapp --template dapp

# With features
cardano-devkit new my-dapp --template dapp --features aiken,react,devnet

# Full options
cardano-devkit new my-nft-marketplace \
  --template nft-marketplace \
  --features aiken,react,testing,ci \
  --network Preprod \
  --package-manager pnpm \
  --git

Templates​

basic​

Simple TypeScript project with DevKit setup.

cardano-devkit new my-project --template basic

Structure:

my-project/
├── package.json
├── tsconfig.json
├── .gitignore
├── src/
│   └── index.ts
└── README.md

dapp​

Full dApp structure with frontend and backend.

cardano-devkit new my-dapp --template dapp

Structure:

my-dapp/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts
│   ├── app/
│   ├── services/
│   └── utils/
├── tests/
└── README.md

nft-marketplace​

NFT marketplace with minting and trading.

cardano-devkit new my-marketplace --template nft-marketplace

Structure:

my-marketplace/
├── src/
│   ├── contracts/
│   ├── marketplace/
│   ├── minting/
│   └── metadata/
├── validators/ (if aiken feature)
└── README.md

defi​

DeFi application with common patterns.

cardano-devkit new my-defi --template defi

Structure:

my-defi/
├── src/
│   ├── contracts/
│   ├── pool/
│   ├── swap/
│   ├── liquidity/
│   └── oracle/
├── validators/
└── README.md

governance​

DAO and governance project.

cardano-devkit new my-dao --template governance

Structure:

my-dao/
├── src/
│   ├── contracts/
│   ├── proposals/
│   ├── voting/
│   ├── treasury/
│   └── drep/
├── validators/
└── README.md

aiken-only​

Pure Aiken smart contract project.

cardano-devkit new my-contracts --template aiken-only

Structure:

my-contracts/
├── aiken.toml
├── validators/
│   └── main.ak
├── lib/
├── README.md
└── .github/

library​

Reusable library for other projects.

cardano-devkit new my-lib --template library

Structure:

my-lib/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts
│   └── lib/
├── tests/
├── docs/
└── README.md

Features​

Add optional features to any template:

aiken​

Adds Aiken smart contract support.

--features aiken

Includes:

  • aiken.toml configuration
  • validators/ directory
  • Aiken build scripts
  • Contract deployment helpers

react​

Adds React frontend with Vite.

--features react

Includes:

  • Vite configuration
  • React components
  • CardanoProvider setup
  • Wallet connection UI

nextjs​

Adds Next.js framework.

--features nextjs

Includes:

  • Next.js configuration
  • API routes
  • SSR setup
  • Wallet integration

devnet​

Adds local devnet configuration.

--features devnet

Includes:

  • Docker Compose for devnet
  • Devnet configuration
  • Faucet setup
  • Local testing scripts

testing​

Adds comprehensive testing setup.

--features testing

Includes:

  • Jest configuration
  • Test utilities
  • Example tests
  • Coverage reporting

ci​

Adds CI/CD configuration.

--features ci

Includes:

  • GitHub Actions workflows
  • Build pipeline
  • Test pipeline
  • Release automation

docker​

Adds Docker configuration.

--features docker

Includes:

  • Dockerfile
  • docker-compose.yml
  • Multi-stage builds
  • Production optimization

docs​

Adds documentation setup.

--features docs

Includes:

  • Docusaurus setup
  • API documentation
  • Getting started guide
  • Example documentation

Configuration​

ScaffoldConfig​

interface ScaffoldConfig {
  // Project name (required)
  name: string;

  // Project template (default: 'basic')
  template?: ProjectTemplate;

  // Optional features to include
  features?: ProjectFeature[];

  // Target directory (default: current)
  directory?: string;

  // Network to target (default: 'Preprod')
  network?: 'Mainnet' | 'Preprod' | 'Preview';

  // Package manager (default: 'pnpm')
  packageManager?: 'npm' | 'pnpm' | 'yarn';

  // Author name
  author?: string;

  // License (default: 'MIT')
  license?: string;

  // Initialize git repository (default: true)
  git?: boolean;

  // Install dependencies after scaffold (default: false)
  installDeps?: boolean;
}

ScaffoldResult​

interface ScaffoldResult {
  // Whether scaffolding was successful
  success: boolean;

  // Project directory path
  projectPath: string;

  // Created files
  files: string[];

  // Created directories
  directories: string[];

  // Next steps for the user
  nextSteps: string[];

  // Warnings or notes
  warnings: string[];
}

Programmatic Usage​

Basic Scaffolding​

import { scaffold } from 'cardano-devkit';

const result = await scaffold({
  name: 'my-dapp',
  template: 'dapp',
  features: ['aiken', 'react', 'testing'],
  network: 'Preprod',
  packageManager: 'pnpm',
  author: 'Your Name',
  git: true,
  installDeps: true,
});

if (result.success) {
  console.log('Project created at:', result.projectPath);
  console.log('\nNext steps:');
  result.nextSteps.forEach(step => console.log(`  - ${step}`));
}

List Available Templates​

import { getTemplates } from 'cardano-devkit';

const templates = getTemplates();
templates.forEach(t => {
  console.log(`${t.name}: ${t.description}`);
});

List Available Features​

import { getFeatures } from 'cardano-devkit';

const features = getFeatures();
features.forEach(f => {
  console.log(`${f.name}: ${f.description}`);
});

Validate Configuration​

import { validateScaffoldConfig } from 'cardano-devkit';

const config = {
  name: 'my-project',
  template: 'invalid-template',
};

const validation = validateScaffoldConfig(config);
if (!validation.valid) {
  console.error('Errors:', validation.errors);
}

Generated Files​

package.json​

Customized based on template and features:

{
  "name": "my-dapp",
  "version": "0.1.0",
  "type": "module",
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch",
    "test": "jest",
    "lint": "eslint src/"
  },
  "dependencies": {
    "@lucid-evolution/lucid": "^0.4.0",
    "cardano-devkit": "^0.2.0"
  }
}

tsconfig.json​

Configured for ESM and target environment:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "outDir": "./dist",
    "rootDir": "./src"
  }
}

Main Entry Point​

Ready-to-run with DevKit:

import { createDevKit, adaToLovelace } from 'cardano-devkit';

const devKit = createDevKit({
  network: 'Preprod',
});

async function main() {
  console.log('🚀 Starting my-dapp...');
  await devKit.init();
  console.log('✅ Connected to', devKit.getNetwork());
}

main().catch(console.error);

Best Practices​

  1. Choose the right template - Start with the closest match
  2. Add only needed features - Keep projects lean
  3. Use Preprod for development - Safe testing environment
  4. Enable testing feature - Ensures code quality
  5. Add CI for production - Automated quality checks
  6. Initialize git - Version control from the start

Next Steps After Scaffolding​

A typical workflow after scaffolding:

# Navigate to project
cd my-dapp

# Install dependencies (if not done during scaffold)
pnpm install

# Start development
pnpm dev

# In another terminal, start devnet (if feature enabled)
cd devnet && docker-compose up -d

# Run tests
pnpm test

# Build for production
pnpm build