Skip to main content

​
Local Installation

Set up Utopia on your local machine to contribute to development, customize the fleet builder, or work with the ship data offline.

​
Prerequisites

Before installing Utopia, ensure you have the following tools installed:
1

Install Node.js

Utopia requires Node.js for building and running the development environment.Download and install Node.js from nodejs.orgVerify your installation:
node --version
npm --version
Use Node.js LTS (Long Term Support) version for best compatibility.
2

Install Grunt CLI

Utopia uses Grunt as its build tool. Install the Grunt command-line interface globally:
npm install -g grunt-cli
Verify the installation:
grunt --version
You may need to use sudo on macOS/Linux or run as Administrator on Windows if you encounter permission errors.

​
Installation Steps

1

Clone the Repository

Clone the Utopia repository from GitHub:
git clone https://github.com/AngryTribble/Star-Trek-Attack-Wing-Utopia.git
cd Star-Trek-Attack-Wing-Utopia
This downloads the complete source code and project history.
2

Install Dependencies

Install all required npm packages:
npm install
This command downloads and installs:
  • Build tools (Grunt plugins)
  • AngularJS and dependencies
  • Development utilities
The installation may take a few minutes depending on your internet connection.
If you encounter errors during npm install, try deleting the node_modules folder and package-lock.json, then run npm install again.
3

Build the Application

Generate the application files:
npm start
This runs the default Grunt task which:
  • Compiles Angular templates
  • Minifies JavaScript files
  • Processes and minifies CSS
  • Generates the ship data JSON
  • Copies assets to the staw-utopia directory
The built application will be in the staw-utopia/ directory.
4

View Your Local Build

Open staw-utopia/index.html in your web browser to view the fleet builder.Alternatively, serve it with a local web server:
npm run serve
Then open http://localhost:8000 in your browser.

​
Project Structure

Understanding the directory structure will help you navigate the codebase: 
Star-Trek-Attack-Wing-Utopia/
├── src/                      # Source files
│   ├── js/                   # JavaScript source
│   ├── css/                  # Stylesheets
│   ├── templates/            # Angular templates
│   ├── data/                 # Ship and card data
│   ├── img/                  # Images and icons
│   └── index.html            # Main HTML file
├── staw-utopia/              # Built application (generated)
├── gruntfile.js              # Grunt build configuration
├── package.json              # Project dependencies
└── README.md                 # Project documentation
Important: Do not manually edit files in the staw-utopia/ directory. These files are automatically generated by the build process and will be overwritten when you run npm start.

​
Development Workflow

​
Watch Mode

For active development, use watch mode to automatically rebuild when files change: 
npm run watch
This monitors your source files and triggers rebuilds automatically when you save changes.
Run npm run watch in a separate terminal window while you code. Your changes will be reflected immediately after each save.

​
Development with Auto-Build

Combine initial build with watch mode: 
npm run dev
This runs npm start followed by npm run watch.

​
Working with Ship Data

The ship and card data resides in src/data/. To work with the data: 
npm run lint-data
The generated staw-utopia/data/data.json file contains the compiled ship database.
To inspect the generated data.json file, use a JSON prettifier tool. The raw file is minified and difficult to read.

​
Available Scripts

Utopia provides several npm scripts for common tasks:
ScriptCommandDescription
Buildnpm start or npm run buildBuild the complete application
Watchnpm run watchWatch for changes and rebuild automatically
Devnpm run devBuild and start watch mode
Servenpm run serveBuild and serve on http://localhost:8000
Datanpm run dataLint and generate ship data
Lint Datanpm run lint-dataValidate ship data files
Generate Datanpm run generate-dataCompile ship data to JSON

​
Build Tasks

Grunt organizes the build into specific tasks: 
grunt build-js
You can run individual tasks during development to speed up your workflow.

​
Troubleshooting

​
Build Fails

If the build fails:
  1. Ensure all prerequisites are installed
  2. Delete node_modules/ and run npm install again
  3. Check that you’re using a compatible Node.js version
  4. Review the error message for specific issues

​
Watch Mode Not Working

If watch mode doesn’t detect changes:
  1. Ensure you’re editing files in src/, not staw-utopia/
  2. Try stopping and restarting watch mode
  3. Check file permissions

​
Port Already in Use

If port 8000 is already in use when running npm run serve: 
# Use a different port
http-server -p 8080 staw-utopia
The http-server package is included as a dev dependency. If you prefer a different server, you can use any static file server.

​
Next Steps

Now that you have Utopia running locally:
  • Explore the source code in src/
  • Make changes and test them locally
  • Review the ship data format in src/data/
  • Consider contributing improvements back to the project

Data Schema

Explore the codebase structure and data models

Contributing Guide

Learn how to contribute to Utopia

Build docs developers (and LLMs) love

Get started for freeTalk to us