Skip to main content
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

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
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:
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:
FieldValidation
Project NameRequired, 2-100 characters
VersionMust follow semantic versioning (e.g., 1.0.0)
Package IdentifierRequired, 2-214 characters, lowercase, hyphens only, no leading/trailing hyphens
DescriptionOptional, max 500 characters
AuthorRequired, max 200 characters, valid email format if provided
URLRequired, valid HTTP/HTTPS URL

​
Common Issues

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
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!
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
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