@init-spark/umbraco

Init-Spark Umbraco

📋 Description

Init-Spark Umbraco is a comprehensive CLI tool that streamlines the setup of Umbraco CMS projects with integrated modern frontend technologies. It automates the entire project initialization process, including:

• ✅ .NET SDK installation and configuration
• ✅ Umbraco CMS installation
• ✅ Frontend framework setup (Vue/Nuxt, React/Next, or Gulp)
• ✅ Git repository initialization
• ✅ Solution file creation
• ✅ Pre-configured project structure with best practices

🚀 Quick Start

Create a new Umbraco project with a single command:

npx @init-spark/umbraco

Follow the interactive prompts to configure your project:

1. Choose your project name
2. Select Umbraco version
3. Pick your frontend technology (Vue, React, or Gulp)
4. Configure additional options

✨ Features

• 🔧 Zero Configuration: Get started immediately without manual setup
• 🎨 Multiple Frontend Options: Choose between Vue/Nuxt, React/Next, or Gulp
• ⚡ Fast Setup: Automated installation and configuration
• 📦 Pre-configured Structure: Industry-standard project organization
• 🔄 Git Integration: Automatic repository initialization with proper .gitignore
• 💼 Solution File: Visual Studio solution file created automatically
• 🎯 Template System: Pre-built templates for components and modules

📖 Getting Started

Prerequisites

Before starting, ensure you have:

• Node.js (v14 or higher)
• npm or yarn package manager
• .NET SDK (will be installed automatically if not present)

Installation & Setup

After the initial setup is complete, follow these steps to get your Umbraco project running:

1. Run the Umbraco Project

Navigate to your project directory and start the application:

cd YourProjectName
dotnet run

Or specify the project explicitly:

dotnet run --project YourProjectName

The application will start and the accessible URL will be displayed in the terminal/console.

2. Complete Umbraco Installation

On the first run, complete the Umbraco installation wizard:

1. Open your browser and navigate to the URL displayed in the terminal
2. Follow the setup wizard:
   • Select your database provider (SQL Server, SQLite, etc.)
   • Configure database connection
   • Create your admin account (username, email, and password)
   • Configure basic settings
3. Complete setup and log in to the Umbraco backoffice at /umbraco

3. Start Developing

Your project is now ready for development:

• Frontend Development:
  • For Gulp: Run gulp in the frontend directory
  • For React/Next: Run npm run dev in the frontend directory
  • For Vue/Nuxt: Run npm run dev in the frontend directory
• Umbraco Backoffice: Access at https://localhost:XXXX/umbraco to manage content
• Template Customization: Edit Razor views in the Views/ folder

Development Workflow

# Terminal 1: Run Umbraco backend
cd YourProjectName
dotnet run

# Terminal 2: Run frontend build process (in another terminal)
cd YourProjectName/Frontend
npm run dev  # or gulp watch for Gulp projects

📁 Project Structure

After running the tool, your Umbraco project will have the following structure:

Root Level

YourProjectName/
├── 📄 YourProjectName.sln          # Visual Studio solution file
├── 📁 YourProjectName/             # Main Umbraco project
│   ├── 📁 Frontend/                # Frontend code (Gulp/React/Vue)
│   ├── 📁 Views/                   # Umbraco Razor views
│   ├── 📁 wwwroot/                 # Static files (CSS, JS, images)
│   ├── ⚙️ appsettings.json         # Umbraco configuration
│   └── 📄 Program.cs               # Application entry point
├── 📄 package.json                 # Frontend dependencies
└── 📄 .gitignore                   # Git ignore rules

Frontend Directory Structure

The structure of the Frontend/ directory varies depending on your chosen technology:

Frontend/
├── 📄 gulpfile.js                  # Gulp task configuration
├── 📄 main.js                      # Main JavaScript entry point
├── 📁 components/                  # Reusable UI components
│   └── componentA/
│       ├── componentA.js
│       └── componentA.scss
├── 📁 modules/                     # Feature modules
│   └── moduleA/
│       ├── moduleA.js
│       └── moduleA.scss
├── 📁 scss/                        # Sass stylesheets
│   ├── main.scss
│   └── core/
│       ├── _colors.scss
│       ├── _reset.scss
│       ├── _skeleton.scss
│       ├── _typography.scss
│       └── _variables.scss
├── 📁 tasks/                       # Custom Gulp tasks
└── 📁 utils/
    └── utils.js                    # JavaScript utilities

Frontend/
├── 📄 package.json
├── 📄 next.config.js              # Next.js configuration (if using Next)
├── 📁 src/
│   ├── 📁 components/              # React components
│   ├── 📁 pages/                   # Next.js pages (if using Next.js)
│   ├── 📁 styles/                  # CSS/SCSS files
│   └── 📁 utils/                   # Utility functions
└── 📁 public/                      # Static assets

Frontend/
├── 📄 package.json
├── 📄 nuxt.config.js              # Nuxt.js configuration (if using Nuxt)
├── 📁 src/
│   ├── 📁 components/              # Vue components
│   ├── 📁 pages/                   # Nuxt.js pages (if using Nuxt.js)
│   ├── 📁 assets/                  # CSS/SCSS files
│   └── 📁 composables/             # Vue composables
└── 📁 public/                      # Static assets

Umbraco Views Structure

The Umbraco template structure for rendering content:

Views/
├── 📁 Partials/
│   ├── 📁 Renderization/
│   │   └── Render_Modules.cshtml         # Helper for rendering modules
│   ├── 📁 WebsiteBase/                   # Base website templates
│   └── 📁 WebsiteContent/
│       ├── 📁 Components/                 # Umbraco component views
│       └── 📁 Modules/
│           └── Content/
│               └── ModuleA/
│                   └── Render_ModuleA.cshtml
└── [Your custom views]

Key Directories Explained

🛠️ Technology Stack

Backend

• Umbraco CMS - Modern .NET CMS platform
• .NET SDK - Cross-platform .NET runtime
• C# - Primary backend language

Frontend Options

• Vue.js / Nuxt.js - Progressive JavaScript framework
• React / Next.js - Popular component-based library
• Gulp - Task runner for build automation

Additional Tools

• Git - Version control
• TypeScript - Type-safe JavaScript (optional)
• Sass/SCSS - CSS preprocessor

💡 Best Practices

Recommended Workflow

1. Start with Umbraco: Set up your content types and document structure first
2. Create Templates: Build Razor views for your content types
3. Develop Frontend: Build components and styles for your templates
4. Test Locally: Always test changes before deployment
5. Use Version Control: Commit frequently with descriptive messages

Tips

• 💾 Backup regularly: Especially before major updates
• 📝 Document your content types: Keep documentation for custom properties
• 🎯 Use partial views: Create reusable Razor components
• ⚡ Optimize assets: Minify CSS/JS for production
• 🔒 Secure your installation: Follow Umbraco security best practices

⚠️ Important Notes

Git Repository

⚠️ Important: When adding Init-Spark Umbraco to an existing Git repository, it is recommended to use an empty repository to avoid conflicts with existing files.

Database Configuration

On first run, you'll need to configure your database. For development:

• SQLite: Simplest option, no additional setup required (automatically configured if using automatic installation)
• SQL Server: Requires SQL Server installation (only available with manual database configuration)
• MySQL/PostgreSQL: Requires additional provider installation (only available with manual database configuration)

Note: If you chose automatic installation during setup, SQLite will be pre-configured. Manual database configuration is only required if you opted out of automatic setup.

📝 License

This project is licensed under the MIT License. See the LICENSE file for full details.

What this means

• ✅ Commercial use allowed
• ✅ Modification allowed
• ✅ Distribution allowed
• ✅ Private use allowed

💖 Support the Project

If you find this tool helpful, consider supporting its development:

Your support helps maintain and improve the tool for everyone!

📚 Additional Resources

• Umbraco Documentation
• .NET Documentation
• Vue.js Guide
• React Documentation
• Gulp Documentation

👤 Author

João Borges