Skip to main content

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