Create Project

The create command initializes a new Native Desktop project with all necessary configuration files, dependencies, and project structure. This command provides an interactive setup process to customize your project.

Prerequisites

Before creating a Native Desktop project, ensure you have:

Node.js (version 16 or higher)
npm or yarn package manager
An empty directory for your project

The CLI will only create projects in empty directories. If your directory contains any files or folders, the command will fail with an error.

Basic Usage

To create a new project, navigate to an empty directory and run:

native-desktop create

It is not possible to set a custom path; the recommended workflow is to create a new folder and run the CLI from there.

Interactive Setup

The create command launches an interactive setup wizard that guides you through the project configuration process.

Step 1: Select Project Type

The CLI first prompts you to select a project type:

? Select the project type: (Use arrow keys)
❯ Empty Project
  Manual Project

Available Project Types

Empty Project

Creates a new project with minimal default settings, perfect for starting from scratch. This option provides:

Basic project structure
Essential configuration files
Minimal boilerplate code
Quick setup process

Best For: Beginners or simple applications

Manual Project

Creates a fully customizable project with comprehensive default settings. This option includes:

Complete project structure
Advanced configuration options
Development tools setup
Extended boilerplate code

Best For: Advanced users who want complete control and manual configuration

Step 2: Project Configuration

After selecting the project type, you’ll be prompted to provide project details:

Project Name

? Enter a name for your project (e.g. "My App"):

Required: Yes
Min Length: 2 characters
Max Length: 100 characters
Example: My Awesome App

This is the human-readable name displayed to users.

Project Version

? Enter the initial version of your project (e.g. "1.0.0"):

Required: Yes
Default: 1.0.0
Format: Semantic versioning (MAJOR.MINOR.PATCH)
Example: 1.0.0, 0.1.0, 2.3.4

The version must follow Semantic Versioning format: MAJOR.MINOR.PATCH

Package Identifier

? Enter the package identifier (e.g. "my-app"):

Required: Yes
Auto-generated: Based on project name (if not provided)
Min Length: 2 characters
Max Length: 214 characters
Format: Lowercase letters, numbers, and hyphens only
Restrictions: Cannot start or end with a hyphen
Example: my-awesome-app

This identifier is used internally and in package manifests.

Project Description

? Enter a brief description of your project (e.g. "A task management app for teams"):

Required: No
Default: A NativeDesktop Application
Max Length: 500 characters
Example: A powerful task management application for remote teams

Author Information

? Enter the author name (e.g. "Jane Doe <hi@native-desktop.com>"):

Required: Yes
Default: NativeDesktop
Max Length: 200 characters
Format: Name or Name with email in angle brackets
Example: John Smith <john@example.com>

You can include an email address in angle brackets: Jane Doe <jane@example.com>

Project URL

? Enter your project's domain URL (e.g. "https://nativedesktop.com"):

Required: Yes
Format: Valid HTTP or HTTPS URL
Example: https://example.com

This URL is used in project metadata and application information.

Complete Example

Here’s a complete example of the project creation flow:

$ native-desktop create

✔ Select the project type: Manual Project
✔ Enter a name for your project (e.g. "My App"): Task Manager Pro
✔ Enter the initial version of your project (e.g. "1.0.0"): 1.0.0
✔ Enter the package identifier (e.g. "my-app"): task-manager-pro
✔ Enter a brief description of your project (e.g. "A task management app for teams"): 
  A professional task management application with team collaboration features
✔ Enter the author name (e.g. "Jane Doe <author@nativedesktop.com>"): 
  Jane Smith <jane@taskmanager.com>
✔ Enter your project's domain URL (e.g. "https://nativedesktop.com"): 
  https://taskmanager.com

Creating project...
✓ Created project structure
✓ Generated configuration files
✓ Installing dependencies...
✓ Project created successfully!

Next steps:
  1. Start development: native-desktop run
  2. Build for production: native-desktop build --target dmg

Generated Project Structure

After creation, your project will have the following structure:

project-directory/
├── src/                          # Source code directory
├── package.json                  # Project dependencies and scripts
├── native-desktop.config.json5   # Native Desktop configuration
├── tsconfig.json                 # TypeScript configuration
├── .eslintrc.json               # ESLint configuration
├── .prettierrc                  # Prettier configuration
├── .gitignore                   # Git ignore rules
└── .npmrc                       # npm configuration

Configuration Files

The create command generates several configuration files:

native-desktop.config.json5
tsconfig.json
.eslintrc.json
.prettierrc

The main configuration file for your Native Desktop application. Contains build settings, application metadata, and platform-specific options.

Post-Creation Steps

After creating your project, you can:

1. Install Dependencies

If dependencies weren’t automatically installed:

npm install

2. Start Development

Run your application in development mode:

native-desktop run

3. Explore Configuration

Review and customize the generated native-desktop.config.json5 file to suit your needs.

4. Add Your Code

Start building your application in the src/ directory.

Validation Rules

The create command validates all inputs to ensure a valid project configuration:

Field	Validation
Project Name	Required, 2-100 characters
Version	Must follow semantic versioning (e.g., 1.0.0)
Package Identifier	Required, 2-214 characters, lowercase, hyphens only, no leading/trailing hyphens
Description	Optional, max 500 characters
Author	Required, max 200 characters, valid email format if provided
URL	Required, valid HTTP/HTTPS URL

Common Issues

Directory Not Empty Error

Error: NativeDesktop can only create new projects in an empty folder.Solution: Ensure your directory is completely empty. Remove all files and folders, including hidden files.

# Create a new empty directory
mkdir my-project
cd my-project
native-desktop create

Invalid Package Name

Error: Package identifier must contain only lowercase letters, numbers, and hyphensSolution: Use only lowercase letters, numbers, and hyphens. Avoid spaces, uppercase letters, and special characters.Valid: my-app-123 Invalid: My App, my_app, MyApp!

Invalid Version Format

Error: Version must follow semantic versioning format (e.g., 1.0.0)Solution: Use the semantic versioning format with three numbers separated by dots.Valid: 1.0.0, 0.1.0, 2.3.4 Invalid: 1.0, v1.0.0, 1.0.0-beta

Invalid URL

Error: URL must start with http:// or https://Solution: Provide a complete URL including the protocol.Valid: https://example.com, http://localhost:3000 Invalid: example.com, www.example.com

Best Practices

Naming Convention

Use descriptive, lowercase package identifiers with hyphens (kebab-case)

Version Strategy

Start with 1.0.0 for production-ready apps, or 0.1.0 for early development

Project Type

Choose “Empty Project” for learning, “Manual Project” for production apps

Documentation

Include a meaningful description to help other developers understand your project

Quick Start

Getting started

Tips and Tricks

User Guide

Prerequisites

Basic Usage

Interactive Setup

Step 1: Select Project Type

Available Project Types

Step 2: Project Configuration

Project Name

Project Version

Package Identifier

Project Description

Author Information

Project URL

Complete Example

Generated Project Structure

Configuration Files

Post-Creation Steps

1. Install Dependencies

2. Start Development

3. Explore Configuration

4. Add Your Code

Validation Rules

Common Issues

Best Practices

Naming Convention

Version Strategy

Project Type

Documentation

​Prerequisites

​Basic Usage

​Interactive Setup

​Step 1: Select Project Type

​Available Project Types

​Step 2: Project Configuration

​Project Name

​Project Version

​Package Identifier

​Project Description

​Author Information

​Project URL

​Complete Example

​Generated Project Structure

​Configuration Files

​Post-Creation Steps

​1. Install Dependencies

​2. Start Development

​3. Explore Configuration

​4. Add Your Code

​Validation Rules

​Common Issues

​Best Practices

Naming Convention

Version Strategy

Project Type

Documentation

Prerequisites

Basic Usage

Interactive Setup

Step 1: Select Project Type

Available Project Types

Step 2: Project Configuration

Project Name

Project Version

Package Identifier

Project Description

Author Information

Project URL

Complete Example

Generated Project Structure

Configuration Files

Post-Creation Steps

1. Install Dependencies

2. Start Development

3. Explore Configuration

4. Add Your Code

Validation Rules

Common Issues

Best Practices