Skip to content

MuleSoft Project Folder Structure Best Practices

This guide outlines the recommended folder structure for MuleSoft projects to ensure consistency, maintainability, and alignment with Maven standards.

Standard Directory Layout

Every Mule 4 project should follow this standard Maven layout:

my-mule-project/
├── src/
│   ├── main/
│   │   ├── mule/                    # Mule configuration files (XMLs)
│   │   │   ├── global.xml           # Shared global configurations
│   │   │   ├── error-handler.xml    # Global error handling strategy
│   │   │   ├── api/                 # API Implementation (generated by APIKit)
│   │   │   └── business/            # Business logic flows
│   │   ├── resources/               # Non-Mule resources
│   │   │   ├── api/                 # RAML/OAS specifications
│   │   │   ├── dwl/                 # DataWeave scripts (.dwl)
│   │   │   ├── properties/          # Environment properties (.yaml)
│   │   │   ├── schemas/             # JSON/XML schemas
│   │   │   └── examples/            # Sample data for tests/mocks
│   │   └── java/                    # Custom Java code
│   └── test/
│       ├── munit/                   # MUnit test suites
│       └── resources/               # Test-specific resources (mocks, test data)
├── pom.xml                          # Maven build configuration
├── mule-artifact.json               # Mule application descriptor
└── README.md                        # Application documentation

Key Directories Explained

src/main/mule

Contains the actual Mule flow definitions.

  • Best Practice: Split monolithic XML files into logic units.
  • global.xml: Configuration elements only (HTTP Listener Config, Database Config, etc.).
  • api.xml: The main entry point (APIKit Router).
  • [feature]-impl.xml: Implementation flows for a specific feature.

src/main/resources

Contains external assets needed by the application.

  • dwl/: Store complex DataWeave transformations here as separate .dwl files. Avoid inline scripts longer than 5 lines.
  • properties/: Store externalized configuration. Use environment-specific files (e.g., dev.yaml, prod.yaml).
  • api/: The API definition (RAML or OAS).

src/test/munit

Contains your MUnit test suites.

  • Naming: Match the source file name, e.g., orders-test-suite.xml tests orders-impl.xml.

Naming Conventions

  • Files: Use kebab-case (e.g., process-orders.xml, common-utils.dwl).
  • Directories: Use kebab-case (e.g., business-logic, error-handling).

Why this structure?

  1. Maven Compatibility: Follows the standard src/main/ and src/test/ convention required by the Mule Maven Plugin.
  2. Separation of Concerns: clearly separates code (Mule/Java) from configuration (properties) and tests.
  3. Maintainability: Splitting resources into dwl, examples, and schemas prevents the generic resources folder from becoming cluttered.