at-builder

A streamlined command-line tool for creating, building, and deploying Adobe Target A/B testing activities with modern web technologies.

🎯 Features

• 🏗️ Project Initialization: Set up new projects with complete configuration
• 🎨 Activity Templates: Generate new activities with customizable variations
• ⚡ Smart Building: Development and production builds with hot reload
• 🚀 Adobe Target Deployment: Direct deployment to Adobe Target activities
• 🩺 Health Diagnostics: Automatic configuration validation and fixing
• 📁 Flexible Structure: Configurable activities folder structure
• 🔧 Environment Management: Automatic .env file handling
• 💻 Modern Toolchain: TypeScript, Webpack, Babel, SCSS support

Installation

Install the package globally using NPM:

npm install -g at-builder

🚀 Quick Start

1. Initialize a new project:

atb init

2. Create a new activity:

atb new

3. Build your activity:

atb build

4. Deploy to Adobe Target:

atb deploy

📋 Commands Reference

Core Commands

| Command | Description | Options | | ----------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------- | | atb init | Initialize project with configuration files | | | atb new | Create new Adobe Target activity with variations | | | atb build | Build activity for development | --prod for production | | atb dev | Start development server with file watching | --browser to open browser | | atb deploy | Deploy activity to Adobe Target | --dry-run for testing, --force to override the 60s cooldown | | atb sync | Sync build.config.json with the AT activity (pages, experiences, names) | --scaffold to auto-create missing variation folders | | atb doctor | Diagnose and fix configuration issues | --fix to auto-fix | | atb install-extension | Install the at-builder extension from the Marketplace (defaults to the VSCode code CLI) | --editor agy for Antigravity IDE; --editor cursor, --editor codium, or any VSCode-fork CLI on PATH |

Examples

# Initialize new project
atb init

# Create new activity
atb new

# Development build with hot reload
atb build

# Production build for Adobe Target
atb build --prod

# Development server with browser
atb dev --browser

# Deploy to Adobe Target
atb deploy

# Deploy in dry-run mode (no PUT to Adobe Target)
atb deploy --dry-run

# Force deploy and skip the 60s cooldown lock
atb deploy --force

# Sync build.config.json from Adobe Target
atb sync

# Sync and auto-create any missing variation folders
atb sync --scaffold

# Check project configuration
atb doctor

# Auto-fix configuration issues
atb doctor --fix

🔧 Project Structure

After initialization, your project will have:

your-project/
├── .env                    # Environment configuration
├── adobe.config.js         # Adobe Target API settings
├── watch-config.json       # Build configuration
├── package.json           # NPM configuration
└── Activities/            # Your activities folder
    └── your-activity/     # Activity folder (auto-created)
        ├── Variation-1/   # Test variations
        │   ├── index.js   # Entry point
        │   ├── css/
        │   │   └── style.scss
        │   ├── scripts/
        │   │   └── app.js
        │   └── constants/
        │       └── index.js
        ├── Vanalytics/    # Analytics tracking
        └── shared/        # Shared configuration

⚙️ Configuration

Environment Variables (.env)

# Project Structure
ACTIVITIES_BASE_FOLDER="Activities"
ACTIVITY_FOLDER_NAME="your-activity-name"

# Development Settings
NODE_ENV="development"
PUPPETEER_LANDING_PAGE=""
TARGET_URL=""
LOGIN_URL=""
VARIATION="Variation-1"

# Adobe Target Deployment
ADOBE_CLIENT_ID="your-client-id"
ADOBE_CLIENT_SECRET="your-client-secret"
ADOBE_TENANT=""           # Optional. Your Adobe org slug (e.g."tst123"). Enables clickable AT UI links in deploy/sync output.

Adobe Target Configuration (adobe.config.js)

module.exports = {
    BASE_URL: 'https://mc.adobe.io/target/activities/',
    IMS_TOKEN_URL: 'https://ims-na1.adobelogin.com/ims/token/v1',
    IMS_SCOPE: 'openid,target_sdk'
};

🔄 Workflow

1. Setup: Run atb init to create project configuration
2. Create: Run atb new to generate activity templates
3. Develop: Modify variations in /Activities/{name}/Variation-*/
4. Test: Run atb build for development testing
5. Build: Run atb build --prod for production deployment
6. Deploy: Run atb deploy to deploy to Adobe Target

🩺 Troubleshooting

Health Check

# Diagnose configuration issues
atb doctor

# Automatically fix issues
atb doctor --fix

Common Issues

• Missing .env file: Run atb init or atb doctor --fix
• Build errors: Check ACTIVITY_FOLDER_NAME in .env
• Deploy failures: Verify Adobe credentials in .env
• Missing activity folder: Create activity with atb new

🚨 Advanced Configuration

Custom Activities Folder

You can customize the activities folder location:

# Use a different activities folder
ACTIVITIES_BASE_FOLDER="MyActivities"

Build Scripts Integration

Add to your project's package.json:

{
  "scripts": {
    "build:target": "atb build --prod",
    "deploy:target": "atb deploy",
    "dev:target": "atb dev --browser"
  }
}

🔌 API Integration

For programmatic usage:

const { getVersion, getHelpInfo } = require("at-builder");

// Get version
console.log(getVersion());

// Get help information
console.log(getHelpInfo());

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 Changelog

v1.2.3

• ✨ Added deploy command for Adobe Target deployment
• 🩺 Added doctor command for configuration diagnostics
• 🔧 Automatic .env file updates when creating activities
• 📁 Configurable activities folder structure
• ⚡ Improved environment variable validation
• 🚀 Enhanced error handling and user guidance

Previous Versions

• v1.2.2: Build improvements and bug fixes
• v1.2.1: Enhanced CLI interface
• v1.2.0: Initial public release

🔒 Telemetry & Privacy

atb sends anonymous usage telemetry to help improve the tool. The following is collected on each command invocation:

• User: git user.email, git user.name, OS username (read from your local environment)
• Project: project folder name, absolute project path, ADOBE_TENANT (if set)
• Command: command name and sanitized arguments (values for any arg containing secret / token / key / password are redacted)
• Execution: status (started / success / failed), duration, error message
• System: platform, Node.js version, CLI version
• Identifier: a persistent random clientId stored at ~/.atb-builder/client_id

Events are appended to a local log at ~/.atb-builder/telemetry.jsonl and sent to Google Analytics 4. Every event has a 500–800 ms timeout, so telemetry never blocks CLI execution.

How to disable

Set either of these to false:

# In your project .env
TELEMETRY_ENABLED=false

# Or as a shell environment variable
export TELEMETRY_ENABLED=false

Redirect to your own endpoint

To collect telemetry to your own server instead of (or in addition to) the default GA4 destination:

TELEMETRY_URL="https://your-endpoint.example.com/events"
TELEMETRY_USER="custom-user-id"          # override the identifier
GA_MEASUREMENT_ID="G-XXXXXXX"             # override GA4 destination
GA_API_SECRET="your-api-secret"

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Repository: https://github.com/upesenga/at-builder
• Issues: https://github.com/upesenga/at-builder/issues
• Author: Upendra Sengar
• License: MIT

Made with ❤️ for Adobe Target developers