How to create a new Rell dapp

Creating a new Rell dapp is the first step in your Chromia development journey. This guide shows you how to bootstrap a project, understand the generated structure, and customize it for your needs.

Prerequisites

• Chromia CLI installed
• PostgreSQL database installed and configured
• Basic understanding of command line operations

Alternative: You can also create projects using VS Code with the Chromia extension, which provides a graphical interface for project creation.

Basic project creation

Step 1: Create your dapp

chr create-rell-dapp

This creates a new project called my-rell-dapp with the necessary files:

my-rell-dapp
   |--chromia.yml
   |--src
      |--main.rell
      |--test
         |--arithmetic_test.rell
         |--data_test.rell

Step 2: Explore the project structure

cd my-rell-dapp
ls -la

You'll see this structure:

my-rell-dapp/
├── chromia.yml          # Project configuration
├── src/
│   ├── main.rell        # Main Rell source code
│   └── test/            # Test directory
│       ├── arithmetic_test.rell
│       └── data_test.rell

Running your dapp

Step 1: Start the node

Navigate to your project directory and start a local node:

cd my-rell-dapp
chr node start

This starts a node with your application running on it. All blockchains listed in the blockchains key in chromia.yml get started.

Step 2: Get the Blockchain RID

Locate the Blockchain RID in the terminal output. You need it to interact with your dapp. The Blockchain RID is the hex value following the "Blockchain RID:" tag in the node output.

Step 3: Test your dapp

You can query your dapp in two ways:

Option 1: Using CURL

curl -X GET 'localhost:7740/query/<BlockchainRID>?type=hello_world'

Option 2: Using Chromia CLI

chr query --blockchain-rid <BlockchainRID> hello_world

Both commands should return:

"Hello World!"

Note: Replace <BlockchainRID> with your actual Blockchain RID from the node output.

Tip: For local development, you can use the simpler --local flag instead of specifying the blockchain RID:

chr query --local hello_world

Project customization patterns

Advanced project creation

The chr create-rell-dapp command creates a default project named my-rell-dapp. For custom project names or setups:

# Create default project (named my-rell-dapp)
chr create-rell-dapp

# For custom names, rename after creation
chr create-rell-dapp
mv my-rell-dapp my-custom-dapp

# Or create in a custom directory structure
mkdir my-custom-project
cd my-custom-project
chr create-rell-dapp
# This creates my-rell-dapp inside my-custom-project/

Directory structure customization

Organize your project for larger applications by extending the generated structure:

my-rell-dapp/
├── chromia.yml
├── src/
│   ├── main.rell           # Main entry point (generated)
│   ├── entities/           # Data models (custom)
│   │   ├── user.rell
│   │   └── message.rell
│   ├── operations/         # Business logic (custom)
│   │   ├── user_ops.rell
│   │   └── message_ops.rell
│   ├── queries/           # Data queries (custom)
│   │   ├── user_queries.rell
│   │   └── message_queries.rell
│   └── test/              # Test directory (generated)
│       ├── arithmetic_test.rell  # Generated test
│       ├── data_test.rell        # Generated test
│       ├── user_test.rell        # Custom test
│       └── message_test.rell     # Custom test

Configuration customization

Customize your chromia.yml for development:

blockchains:
  hello:
    module: main

# Development settings (optional)
database:
  schema_version: 1

# Test configuration (optional)
test:
  timeout: 30000
  parallel: true

# Build settings (optional)
build:
  output_dir: build
  optimize: true

Next steps

After creating your dapp:

1. Test your Hello World dapp - Follow the "Running your dapp" section above
2. Run queries - Advanced query patterns and testing
3. Run operations - Test state modifications with chr tx
4. Run tests - Set up comprehensive testing workflows