New Dart Project Setup

This guide describes the minimum standards for setting up a new Dart project in the Tom workspace.

Prerequisites

• Dart SDK installed
• Access to the Tom workspace

Creating a New Project

Required: All new Dart projects MUST be created using dart create:

# For a Dart package/library
dart create -t package my_project_name

# For a console application
dart create -t cli my_project_name

# For a server application
dart create -t server-shelf my_project_name

Do NOT manually create project folders or copy from other projects.

Post-Creation Setup Checklist

After running dart create, apply the following steps to meet workspace standards:

1. Claim a project ID

Get the project ID from projects_and_repos.md. If creating a new project, add an entry there first.

2. Update pubspec.yaml

Verify these fields are set correctly:

name: my_project_name
description: A meaningful one-line description
version: 0.0.1
publish_to: none  # Unless publishing to pub.dev

environment:
  sdk: ^3.5.0     # Use current Dart SDK version

# Add workspace dependencies as needed
dependencies:
  tom_basics:
    path: ../../basics/tom_basics

3. Create _copilot_guidelines/index.md

Create the _copilot_guidelines/ folder and add an index.md:

# Project Name Guidelines

> Type: Dart Package | CLI Tool | Server App | Flutter App

## Global Guidelines

- [Documentation Guidelines](../../../../_copilot_guidelines/documentation_guidelines.md)

## Dart Guidelines

- [Coding Guidelines](../../../../_copilot_guidelines/dart/coding_guidelines.md)
- [Unit Testing](../../../../_copilot_guidelines/dart/unit_tests.md)
- [Examples](../../../../_copilot_guidelines/dart/examples.md)

## Project-Specific Guidelines

*Add project-specific guidelines here as the project develops.*

Count the ../ for your own project. Four is right for a project two sub-repos deep, such as tom_ai/core/tom_core_kernel/_copilot_guidelines/; a project one level shallower, such as tom_uam/tom_uam_server/, needs three.

A leading / does not mean the workspace root — it means the filesystem root, so /_copilot_guidelines/… resolves nowhere and opens neither in VS Code nor on GitHub. Every project index.md in the workspace was written that way, from this template, and not one of those links worked.

4. Set Up analysis_options.yaml

Replace the generated analysis_options.yaml with workspace-standard settings:

include: package:lints/recommended.yaml

analyzer:
  language:
    strict-casts: true
    strict-inference: true
    strict-raw-types: true
  errors:
    # Treat missing required parameters as errors
    missing_required_param: error
    # Treat unused imports as warnings
    unused_import: warning
  exclude:
    - '**/*.g.dart'
    - '**/*.freezed.dart'

linter:
  rules:
    - prefer_single_quotes
    - sort_constructors_first
    - sort_unnamed_constructors_first
    - unnecessary_late
    - unnecessary_null_checks
    - unawaited_futures

5. Create README.md

Replace the generated README with a proper one:

# Project Name

Brief description of the project.

## Installation

dart pub add my_project_name

## Usage

import 'package:my_project_name/my_project_name.dart';

// Example usage code

## Features

- Feature 1
- Feature 2

## Documentation

See `doc/` for the project's own documentation.

6. Configure .gitignore

Ensure these entries exist:

# Dart
.dart_tool/
build/
pubspec.lock  # For packages, keep for apps

# IDE
.idea/
*.iml
.vscode/

# Coverage
coverage/

7. Run Quality Checks

Before committing:

# Get dependencies
dart pub get

# Run analyzer
dart analyze

# Format code
dart format .

# Run tests (if any)
dart test

Project Location

Place new projects in the appropriate folder:

Type	Location
Core framework	core/
DevOps/Build tools	devops/
AI-related	ai_build/
Cloud/Provisioning	cloud/
UAM components	tom_uam/ (a sibling of tom_ai/, not inside it)
SQM components	tom_sqm/ (likewise)
Standalone apps	xternal_apps/
Modules (separate repo)	d4rt/ , basics/ , distributed/ , reflection/ , vscode/ (within tom_ai/ )

Adding to Workspace Registry

After creating the project:

1. Update projects_and_repos.md: Add entry with ID, name, description 2. Update tom.code-workspace: Add to multi-root workspace if needed

Naming Conventions

• Project folder: tom_{category}_{name} (e.g., tom_uam_client)
• Package name in pubspec: Same as folder name
• Project ID: Short uppercase (2-10 chars), see projects_and_repos.md
• Short name: Lowercase, hyphenated (e.g., uam-client)

See Also

• Project Structure
• Projects and Repos
• Coding Guidelines