Create Local App

A powerful Go-based scaffolding tool for TrueBlocks/Wails desktop applications

Explore the docs »

Report Bug · Request Feature

Table of Contents

• Create Local App
  • Table of Contents
  • About The Project
    • Built With
  • Getting Started
    • Prerequisites
    • Installation
  • Usage
    • Command Line Options
    • Interactive Mode (First Run)
    • Auto Mode (Subsequent Runs)
    • Force Mode
    • Template Management
    • Creating Your First TrueBlocks miniDapp
  • Contributing
  • License
  • Contact
  • Acknowledgments

About The Project

create-local-app is a sophisticated scaffolding tool designed to streamline the creation of TrueBlocks/Wails desktop applications. With a single command, it generates a complete project structure with Go backend and TypeScript frontend, handling all the boilerplate code and configuration for you.

Built With

This project is built using modern Go technologies and integrates seamlessly with the TrueBlocks ecosystem:

• 
• 
• 
• 

Getting Started

To get a local copy up and running, follow these simple steps.

Prerequisites

Before using create-local-app, ensure you have the required versions of these tools. Click on the badges in the Built With section for installation instructions.

Required versions:

• Go: v1.23.1 or higher
• TrueBlocks: v5.1.0 or higher
• Wails: v2.10.1 or higher
• Yarn: v1.22.22 or higher

Check your versions:

go version        # v1.23.1 or higher
chifra version    # v5.1.0 or higher 
wails version     # v2.10.1 or higher
yarn --version    # v1.22.22 or higher

Installation

1. Build from source

   git clone https://github.com/TrueBlocks/create-local-app.git
   cd create-local-app
   
   # Build the Go binary (templates are embedded)
   touch VERSION && go build -o bin/create-local-app main.go

2. Install to your PATH (recommended)

   # Option 1: Use the deploy script (easiest)
   yarn deploy
   
   # Option 2: Manual installation
   cp bin/create-local-app /usr/local/bin/
   
   # OR (temporarily) add the bin directory to your PATH
   export PATH="$PATH:$(pwd)/bin"

   📝 Note: If you get a permission error with yarn deploy, you may need to use sudo yarn deploy. This can happen if there's an existing file in /usr/local/bin/ that was previously installed with sudo.

3. Configuration Directory Structure

   On first run, the application automatically creates and populates:

   ~/.create-local-app/
   ├── config.json                 # Your saved preferences
   └── templates/
       ├── system/                 # Built-in templates (extracted from binary)
       │   └── default/            # Default Wails project template
       └── contributed/            # Your custom templates
           └── my-template/        # Created with --create mode
   

   • Embedded Templates: System templates are embedded in the binary as compressed archives
   • Automatic Extraction: Templates are extracted to home directory on first run
   • Contributed Templates: Your custom templates, preserved across updates
   • Configuration: Stores your organization, project defaults, etc.

Usage

When you first run create-local-app, it will interactively prompt you for project information and save your preferences for future use. Subsequent runs can use the --auto flag to skip prompts if nothing has changed.

Command Line Options

• --auto - Use saved configuration without prompts
• --force - Force operation without confirmation (overwrite existing files)
• --create <template-name> - Create a template from the current directory
• --remove <template-name> - Remove a contributed template with confirmation
• --version - Show version information
• --help - Show help message

Interactive Mode (First Run)

The first time you run the command, it provides a guided setup experience:

create-local-app

You'll be prompted for:

• Organization: Your organization name (e.g., "TrueBlocks, LLC")
• Project Name: Name of your project (e.g., "my-awesome-app")
• Go Import: For importing Go packages - no spaces allowed (e.g., "github.com/TrueBlocks/my-awesome-app")
• Domain: The domain name of your home page (e.g., "trueblocks.io")

⚠️ Warning: If the current directory contains files, the operation will fail unless you use the --force flag. This prevents accidental overwrites of existing work.

Auto Mode (Subsequent Runs)

Skip prompts and use previously saved configuration:

create-local-app --auto [--force]

Note: This uses the configuration saved from your previous interactive run and also requires --force if files exist.

Force Mode

Override the safety check that prevents overwriting existing files:

create-local-app --force
# or
create-local-app --auto --force

⚠️ Warning: The --force flag will overwrite existing files in an unrecoverable way. Make sure to commit your changes to version control before using this flag.

Template Management

Create and manage custom templates:

Creating a Template:

# From a customized project, create a template (saves project-local config)
cd my-customized-project
create-local-app --create my-custom-template

Removing a Template:

create-local-app --remove my-custom-template
    # > Are you sure you want to remove template 'my-custom-template'? (y/N):

📝 Note: Only contributed templates can be removed. System templates (like "default") are protected and cannot be removed.

Creating Your First TrueBlocks miniDapp

# 1. Create a new project interactively
mkdir my-new-app && cd my-new-app
create-local-app
    # > TrueBlocks, LLC
    # > my-new-app
    # > github.com/TrueBlocks/my-new-app
    # > https://trueblocks.io 

# 2. Initialize git repository and submodules
git init
git submodule update --init --recursive

# 3. Set up the my-new-app project
yarn install

# 4. Testing
yarn test

# 5. Start the new app
yarn start

# 6. Later, if you need to regenerate (e.g., after template updates)
# This will fail safely if files exist:
create-local-app --auto
    # Error: directory contains files, use --force

# Use --force to override safety check:
create-local-app --auto --force

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

For detailed development information, see DEVELOPING.md.

License

Distributed under the GPL 3.0 License. See LICENSE for more information.

Contact

TrueBlocks - @trueblocks - [email protected]

Project Link: https://github.com/TrueBlocks/create-local-app

Acknowledgments

Resources and inspirations that made this project possible:

• Wails Framework - For creating amazing desktop apps with Go and web technologies
• TrueBlocks - The decentralized data infrastructure
• Go Programming Language - For excellent standard library and tooling
• Best README Template - For this awesome README structure
• Shields.io - For the beautiful badges
• Choose an Open Source License - For license guidance