project-initialization.md

Project Initialization

Use emulsify init to create a new Emulsify project from a starter repository.

emulsify init [name] [path]

The command clones a starter, writes project.emulsify.json, installs dependencies, runs the starter init hook when present, removes the starter .git directory, and prints next-step guidance.

Platform And Starter Resolution

The CLI tries to determine the platform from the current working directory before prompting or using defaults.

Detection	Result
Drupal Composer project with extra.drupal-scaffold.locations.web-root	Platform drupal, target parent <web-root>/themes/custom.
Existing Emulsify project found by project.emulsify.json	Platform none, target parent <project-root>/web/themes/custom.
No detectable platform	Use --platform, prompt in an interactive terminal, or use --yes to accept defaults.

When the platform cannot be detected and stdin is a TTY, the prompt choices are:

? Platform:
❯ drupal
  none

Built-in starter repositories:

Platform	Repository	Checkout
none	https://github.com/emulsify-ds/emulsify-starter	main
drupal	https://github.com/emulsify-ds/emulsify-drupal-starter	main

You can override starter resolution with --starter and --checkout.

Interactive Output

Interactive init asks for missing values, then prints compact next steps. When init detects that it is running inside a Drupal project, it also reminds you to install the required Drupal Composer packages.

✔ Project name: britty
[====================] 100% initialization complete

Created an Emulsify project in britty.

Detected a Drupal project.

Install the required Drupal packages with Composer:
  composer require drupal/emulsify drupal/emulsify_tools
  drush en emulsify_tools -y

The generated Drupal starter uses drupal/emulsify as its base theme and emulsify_tools for Drupal integration, so both packages must exist in the Drupal codebase.

Next, choose a component system:
  emulsify system install

For platform none, or when drupal is selected manually outside a detected Drupal project, the Drupal package reminder is omitted:

Next, choose a component system:
  emulsify system install

Target Directory

The [path] argument is the parent directory. The CLI creates the project inside that parent using the machine name.

emulsify init "Marketing Site" ./projects --platform none

Creates:

./projects/marketing-site

Drupal machine names use underscores:

emulsify init "My Theme" ./web/themes/custom --platform drupal

Creates:

./web/themes/custom/my_theme

If the target already exists, initialization stops with an error and does not overwrite the directory.

Machine Names

If --machineName is omitted, the CLI derives one from the project name by removing non-alphanumeric characters, replacing spaces, and lowercasing the result.

Platform	Project Name	Derived Machine Name
none	Marketing Site	marketing-site
drupal	My Theme	my_theme

Use --machineName when the folder name or Drupal theme machine name must be exact.

emulsify init "My Theme" ./web/themes/custom --platform drupal --machineName custom_theme

Non-Interactive Initialization

In non-TTY environments, the command does not prompt. Provide the needed values as arguments and flags.

emulsify init "Build Theme" ./web/themes/custom --platform drupal --yes

With --yes, missing values use the current defaults:

Value	Default
Project name	emulsifyTheme
Target parent	./
Platform	drupal

Explicit arguments and flags still take precedence over --yes defaults.

In non-interactive mode, provide --platform drupal or --platform none when auto-detection is unavailable.

Custom Starter

Use a custom starter when the built-in starter list does not match the project.

emulsify init "Client Theme" ./web/themes/custom \
  --platform drupal \
  --starter https://github.com/example/client-starter \
  --checkout v1.2.0

If --checkout is omitted, the starter repository default branch is cloned.

Generated Project Configuration

After a Drupal init, the generated project.emulsify.json looks like this:

{
  "project": {
    "platform": "drupal",
    "name": "My Theme",
    "machineName": "my_theme"
  },
  "starter": {
    "repository": "https://github.com/emulsify-ds/emulsify-drupal-starter"
  }
}

Systems and variants are added later by emulsify system install.

Starter Init Hook

If the cloned starter contains .cli/init.js, the CLI runs it with Node.js after dependencies install and before the starter .git directory is removed. The hook process runs with its working directory set to the hook file directory.

Starter hooks are useful for one-time project setup that belongs to the starter rather than the CLI.