### Modular Command File Structure Example

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/constants-and-internals.md

Example of a modular make command file, extending the base command and overriding the `run` method to handle module-specific logic.

```typescript
// commands/make/controller.ts
export default class MMakeController extends MakeController {
  @flags.string(MODULE_FLAG)
  declare module: string

  override async run() {
    // If no module specified, use parent behavior
    if (!this.module) {
      return super.run()
    }

    // Auto-create module if missing
    if (!checkModule(this.app, this.module)) {
      this.kernel.exec(`${COMMAND_PREFIX}:module`, [this.module])
    }

    // Use custom stubs and generate in module
    const codemods = await this.createCodemods()
    await codemods.makeUsingStub(stubsRoot, this.stubPath, {
      flags: this.parsed.flags,
      entity: this.app.generators.createEntity(this.name),
    })
  }
}
```

--------------------------------

### Example Modular Make Commands

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/api-reference/configure.md

After successful installation, these commands become available for creating modular components within an AdonisJS project.

```bash
node ace make:module auth
```

```bash
node ace make:controller sign_in --module auth
```

```bash
node ace make:model User --module users
```

--------------------------------

### Controller Creation with Actions

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/command-reference.md

Example of creating a controller with predefined actions like index, store, and show, specifying the module.

```bash
node ace make:controller posts --module blog --actions index,store,show
```

--------------------------------

### Verify Module Installation by Creating a Test Module

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Create a test module to confirm that the installation was successful and that the Ace CLI commands correctly support the --module flag.

```bash
# Create a test module
node ace make:module test_module

# Check it was created
ls -la app/test_module
cat package.json | grep test_module

# Clean up
rm -rf app/test_module
```

--------------------------------

### Middleware Creation with Stack Selection

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/command-reference.md

Example of creating a middleware, specifying its module and the stack it belongs to (e.g., router).

```bash
node ace make:middleware auth --module auth --stack router
```

--------------------------------

### Example: Multiple Modules Registration in package.json

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/configuration.md

Shows the package.json configuration for registering multiple modules ('auth', 'users', 'billing') with their respective import aliases.

```json
{
  "imports": {
    "#auth/*": "./app/auth/*.js",
    "#users/*": "./app/users/*.js",
    "#billing/*": "./app/billing/*.js"
  }
}
```

--------------------------------

### Project Structure Example

Source: https://github.com/adonisjs-community/modules/blob/main/README.md

Illustrates a typical project structure organized into modules like 'auth' and 'users' within the 'app' directory.

```directory
├── app
│  ├── auth
│  │  ├── controllers
│  │  ├── services
│  │  └── models
│  └── users
│     ├── exceptions
│     ├── factories
│     └── validators
```

--------------------------------

### Importing Configuration Function

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/INDEX.md

Import the `configure` function from the package for setup.

```typescript
import { configure } from '@adonisjs-community/modules'
import type { ApplicationService } from '@adonisjs/core/types'
```

--------------------------------

### Event Listener Setup with Automatic Event Creation

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/README.md

Shows how to set up an event listener for a specific module, which also automatically creates the corresponding event class if it doesn't exist.

```bash
node ace make:listener on_user_created --module users --event user_created
```

--------------------------------

### Feature Module Setup Workflow

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/README.md

A comprehensive workflow for setting up a complete feature module, including creating the module and generating various components like controllers, services, middleware, and exceptions.

```bash
# Create module
node ace make:module auth

# Create auth components
node ace make:controller sign_in --module auth
node ace make:controller sign_up --module auth
node ace make:service auth_service --module auth
node ace make:middleware auth_check --module auth
node ace make:exception invalid_credentials --module auth
node ace make:validator login_credentials --module auth
```

--------------------------------

### Install and Verify @adonisjs-community/modules

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Install the package using the Ace CLI and verify its installation by checking the help command for module support.

```bash
# Install the package
node ace add @adonisjs-community/modules

# Verify installation
node ace make:module --help
```

--------------------------------

### Importing Command Groups

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/README.md

This example shows how command groups are imported, which are automatically registered by the `configure` function.

```typescript
// Command groups (auto-registered by configure)
import('@adonisjs-community/modules/commands')
```

--------------------------------

### Example: Importing from a Single Module

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/configuration.md

Demonstrates how to import controllers, services, and models from the 'auth' module using the registered alias '#auth/*'.

```typescript
// Import controller from auth module
import { SignInController } from '#auth/controllers/sign_in_controller'

// Import service from auth module
import { AuthService } from '#auth/services/auth_service'

// Import model from auth module
import { User } from '#auth/models/user'
```

--------------------------------

### Package.json Imports Configuration

Source: https://github.com/adonisjs-community/modules/blob/main/README.md

Example of how the package.json file is updated to register a new alias for the created module path.

```json
{
  "imports": {
    "...",
    "#auth/*": "./app/auth/*.js"
  }
}
```

--------------------------------

### Module-Relative Middleware Registration Example

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/README.md

Demonstrates how middleware is registered using module-relative import aliases, ensuring consistency with module organization.

```typescript
// Middleware registered as:
() => import('#middleware/auth/auth_check')
```

--------------------------------

### Example: Importing from Multiple Modules

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/configuration.md

Illustrates parallel imports from different modules ('auth', 'users', 'billing') using their defined aliases.

```typescript
import { AuthService } from '#auth/services/auth_service'
import { User } from '#users/models/user'
import { BillingService } from '#billing/services/billing_service'
```

--------------------------------

### Module-Relative Provider Registration Example

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/README.md

Shows how service providers are registered using module-relative import aliases, maintaining consistency with module structure.

```typescript
// Provider registered as:
() => import('#providers/auth_provider')
```

--------------------------------

### Install AdonisJS Modules

Source: https://github.com/adonisjs-community/modules/blob/main/README.md

Command to install the @adonisjs-community/modules package into an existing AdonisJS project.

```bash
node ace add @adonisjs-community/modules
```

--------------------------------

### Same Module Imports

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/module-structure-and-patterns.md

Shows examples of importing models and services from within the same module, which is always safe.

```typescript
import { User } from '#users/models/user'
import { UserService } from '#users/services/user_service'
```

--------------------------------

### Auto-Module Creation with Controller

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/command-reference.md

Example of creating a controller where the specified module does not exist. The command automatically creates the module first.

```bash
node ace make:controller sign_in --module auth
```

--------------------------------

### Module Naming Conventions with Ace CLI

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/module-structure-and-patterns.md

Examples of using the 'ace make:module' command to create modules, demonstrating how different input styles (PascalCase, camelCase, kebab-case, snake_case) are converted to snake_case for internal module aliases.

```bash
node ace make:module User              # → #user/*
node ace make:module userAuth          # → #user_auth/*
node ace make:module user-auth         # → #user_auth/*
node ace make:module user_auth         # → #user_auth/*
```

--------------------------------

### Importing Main Export

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/README.md

This example demonstrates how to import the main export from the '@adonisjs-community/modules' package.

```typescript
// Main export
import { configure } from '@adonisjs-community/modules'
```

--------------------------------

### Generate Module Components with Ace CLI

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/README.md

Examples of generating controllers, services, models, and factories within specific modules using the `--module` flag.

```bash
# Create controller in auth module
node ace make:controller sign_in --module auth

# Create service in auth module
node ace make:service auth_service --module auth

# Create model in users module (creates module if missing)
node ace make:model user --module users

# Create factory in users module
node ace make:factory user --module users
```

--------------------------------

### Displaying Specific Command Help

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/command-reference.md

Command to display detailed help for a specific ACE command, including its arguments, flags, and examples.

```bash
node ace make:module --help
```

```bash
node ace make:controller --help
```

```bash
node ace make:model --help
```

--------------------------------

### Example: Single Module Registration in package.json

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/configuration.md

Illustrates how to register a single module, 'auth', in package.json after running 'node ace make:module auth'. This sets up the import alias for the auth module.

```json
{
  "name": "my-adonisjs-app",
  "imports": {
    "#auth/*": "./app/auth/*.js"
  }
}
```

--------------------------------

### AdonisJS Module Structure Example

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/README.md

Illustrates a typical modular project structure within the `/app` directory, organizing code by feature such as authentication and user management.

```directory
app/
├── auth/              # Auth module
│   ├── controllers/
│   ├── services/
│   └── models/
└── users/             # Users module
    ├── controllers/
    ├── models/
    └── factories/
```

--------------------------------

### Create a New Module

Source: https://github.com/adonisjs-community/modules/blob/main/README.md

Command to create a new module, for example, 'auth', within the AdonisJS project structure.

```bash
node ace make:module auth
```

--------------------------------

### Module Directory Structure Example

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/configuration.md

Illustrates the optional directory structure for a self-contained module within an AdonisJS application. Not all subdirectories are required; create only those needed.

```plaintext
app/
└── <moduleName>/
    ├── controllers/          # HTTP controllers
    ├── models/               # Lucid ORM models
    ├── services/             # Business logic services
    ├── factories/            # Model factories for testing
    ├── events/               # Class-based events
    ├── listeners/            # Event listeners
    ├── middleware/           # Middleware classes
    ├── commands/             # Ace CLI commands
    ├── providers/            # Service providers
    ├── exceptions/           # Custom exceptions
    ├── validators/           # VineJS validators
    ├── transformers/         # API transformers
    └── views/                # Edge.js templates
```

--------------------------------

### Multi-Step Feature Module Structure

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/module-structure-and-patterns.md

Example of a directory structure for a multi-step feature like checkout, showcasing separation of concerns across models, services, controllers, validators, events, and listeners.

```directory
app/
└── checkout/
    ├── models/
    │   ├── order.ts
    │   ├── payment.ts
    │   └── shipment.ts
    ├── services/
    │   ├── order_service.ts
    │   ├── payment_service.ts
    │   └── shipment_service.ts
    ├── controllers/
    │   ├── orders_controller.ts
    │   └── payments_controller.ts
    ├── validators/
    │   ├── create_order.ts
    │   └── process_payment.ts
    ├── events/
    │   ├── order_placed.ts
    │   ├── payment_received.ts
    │   └── order_shipped.ts
    └── listeners/
        ├── on_order_placed.ts           # Reserves inventory
        ├── on_payment_received.ts       # Triggers fulfillment
        └── on_order_shipped.ts          # Sends tracking email
```

--------------------------------

### Module Creation with PascalCase Name

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/api-reference/make-module-command.md

When using PascalCase for module names, the command automatically converts it to snake_case for directory and package.json entries. This example creates a 'UserManagement' module.

```bash
node ace make:module UserManagement
```

--------------------------------

### Test File Structure Configuration

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/configuration.md

Demonstrates the structure for test files, which follows suite configuration from `.adonisrc.ts` rather than module-specific paths. Examples show unit and functional test placement.

```plaintext
tests/
├── unit/
│   └── services/
│       └── [created via make:test --module users]
└── functional/
    └── [created via make:test --module auth --suite=functional]
```

--------------------------------

### Provider Creation with Environments

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/command-reference.md

Demonstrates creating a provider, specifying its module and the environments it should be registered in (e.g., web, console).

```bash
node ace make:provider mail --module notifications --register --environments web,console
```

--------------------------------

### Workflow: Create Module then Components

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/api-reference/make-module-command.md

This sequence demonstrates a common workflow: first creating a module, then using other `make:` commands with the `--module` flag to add components like controllers, services, and models within that module.

```bash
# Create module first
node ace make:module auth

# Then create components within that module
node ace make:controller sign_in --module auth
node ace make:service auth_service --module auth
node ace make:model user --module auth
node ace make:factory user_factory --module auth
```

--------------------------------

### Create Product Model and Migration

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Generate the 'Product' model and its corresponding database migration file for the 'products' module. This step assumes you will accept the default prompts for creating a controller and factory.

```bash
node ace make:model product --module products
```

--------------------------------

### Check specific module file

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Display the content of a specific file within a module, for example, 'app/users/models/user.ts'.

```bash
cat app/users/models/user.ts
```

--------------------------------

### Create Products Controller with CRUD Actions

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Generate an HTTP controller for 'products' within the 'products' module, including predefined actions for index, store, show, update, and destroy.

```bash
node ace make:controller products --module products --actions index,store,show,update,destroy
```

--------------------------------

### Create and Register Service Provider

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/README.md

Use this command to create a new service provider and automatically register it for specified environments.

```bash
node ace make:provider mail_provider --module notifications --register --environments web,console
```

--------------------------------

### Create Controller within a Module

Source: https://github.com/adonisjs-community/modules/blob/main/README.md

Demonstrates how to create a controller, 'sign_in', within a specific module, 'auth', using the -m or --module flag.

```bash
node ace make:controller sign_in -m=auth
```

```bash
node ace make:controller sign_in --module auth
```

--------------------------------

### Automatic .adonisrc.ts Command Registration

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/configuration.md

Shows how the '@adonisjs-community/modules' package automatically adds its commands to the `.adonisrc.ts` file upon installation.

```typescript
import { defineConfig } from '@adonisjs/core/build/config'

export default defineConfig({
  commands: [
    () => import('@adonisjs/core/commands'),
    () => import('@adonisjs/lucid/commands'),
    () => import('@adonisjs-community/modules/commands'),  // <- Added automatically
  ],
  
  // ... rest of config
})
```

--------------------------------

### Model Creation with Multiple Flags

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/command-reference.md

Shows how to create a model along with its associated factory and controller using multiple flags.

```bash
node ace make:model User --module users --factory --controller
```

--------------------------------

### Module Creation for Features

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/module-structure-and-patterns.md

Demonstrates the best practice of creating separate modules for distinct features like users, posts, and comments.

```bash
# Good: Each feature has its own module
node ace make:module users
node ace make:module posts
node ace make:module comments
```

--------------------------------

### Circular Dependency Example

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/module-structure-and-patterns.md

Highlights a circular dependency scenario between two modules, which should be avoided. Events are recommended for loose coupling.

```typescript
// users/models/user.ts imports from auth
import { AuthService } from '#auth/services/auth_service'

// auth/services/auth_service.ts imports from users
import { User } from '#users/models/user'  // ✗ Circular!
```

--------------------------------

### Run Tests

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/constants-and-internals.md

Execute the test suite using npm scripts. Use 'npm run quick:test' for tests without coverage, or 'npm test' for tests with coverage reporting.

```bash
npm run quick:test      # No coverage
```

```bash
npm test               # With coverage
```

--------------------------------

### Using the --module Flag with make:* Commands

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/configuration.md

Demonstrates how to use the `--module` flag with various `make:*` commands to specify the module for which the generated file should be created.

```bash
# Available on any make command
node ace make:controller <name> --module <moduleName>
node ace make:model <name> --module <moduleName>
node ace make:service <name> --module <moduleName>
# ... and so on for all make:* commands
```

--------------------------------

### Create Controller and Service Tests

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Generate test files for the 'products_controller' (functional suite) and 'product_service' (unit suite) within the 'products' module.

```bash
node ace make:test products_controller --module products --suite functional
node ace make:test product_service --module products --suite unit
```

--------------------------------

### Generate Model, Factory, and Controller in One Command

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/README.md

Demonstrates generating a model, its associated factory, and a controller for a module in a single Ace command execution.

```bash
node ace make:model user --module users --factory --controller
```

--------------------------------

### Controller Validation Example

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/module-structure-and-patterns.md

Demonstrates the recommended practice of validating request data within controllers using a validator. Avoids validation in services.

```typescript
// ✓ Good: Validation in controllers
export default class UsersController {
  async store({ request }) {
    const data = await request.validate(CreateUserValidator)
    return this.userService.create(data)
  }
}

// ✗ Avoid: No validation, or validation in services
export default class UserService {
  create(data: any) {
    // Data could be anything
  }
}
```

--------------------------------

### Create Product Service

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Generate a service class for handling business logic related to products within the 'products' module.

```bash
node ace make:service product_service --module products
```

--------------------------------

### Create Authentication Controllers

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Generate controllers for sign-in, sign-up, and sign-out functionalities within the auth module.

```bash
node ace make:controller sign_in --module auth
node ace make:controller sign_up --module auth
node ace make:controller sign_out --module auth
```

--------------------------------

### Create a New Module for a REST API

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Initiate a new module named 'products' using the Ace CLI, which is the first step in building a complete REST API module.

```bash
node ace make:module products
```

--------------------------------

### Command Registration via Entry Point

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/constants-and-internals.md

Explains that commands are registered through the application's entry point, which is automatically indexed during the build process. This is a conceptual note rather than a code snippet.

```bash

```

--------------------------------

### Typical Module Directory Structure

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/module-structure-and-patterns.md

Illustrates a comprehensive module structure with directories for controllers, models, services, factories, events, listeners, middleware, commands, providers, exceptions, validators, transformers, and views.

```text
app/
└── <moduleName>/
    ├── controllers/              # HTTP request handlers
    │   ├── sign_in_controller.ts
    │   └── sign_up_controller.ts
    ├── models/                   # Lucid ORM models
    │   └── user.ts
    ├── services/                 # Business logic
    │   ├── auth_service.ts
    │   └── password_service.ts
    ├── factories/                # Test data generators
    │   └── user_factory.ts
    ├── events/                   # Class-based events
    │   └── user_created.ts
    ├── listeners/                # Event listeners
    │   └── on_user_created.ts
    ├── middleware/               # Request middleware
    │   └── auth_check_middleware.ts
    ├── commands/                 # Ace CLI commands
    │   └── verify_users.ts
    ├── providers/                # Service providers
    │   └── auth_provider.ts
    ├── exceptions/               # Custom exceptions
    │   └── invalid_credentials.ts
    ├── validators/               # VineJS validators
    │   └── login_credentials.ts
    ├── transformers/             # API transformers
    │   └── user_transformer.ts
    └── views/                    # Edge.js templates
        └── login.edge
```

--------------------------------

### Apply module middleware to route group

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Secure a group of routes by applying middleware defined within a module. This example shows applying 'auth' middleware to 'posts' routes.

```typescript
// routes/api.ts
router.group(() => {
  router.resource('posts', PostsController)
}).middleware(['auth'])  // Uses module middleware
```

--------------------------------

### Create Modules for Refactoring

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Scaffolds new module directories for migrating monolithic application code.

```bash
node ace make:module users
node ace make:module products
node ace make:module orders
```

--------------------------------

### Products Controller Implementation

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Handles HTTP requests for the products resource, utilizing the ProductService for business logic and ProductTransformer for response formatting. Includes methods for index, store, and show actions.

```typescript
import { HttpContext } from '@adonisjs/core/http'
import ProductService from '#products/services/product_service'
import CreateProductValidator from '#products/validators/create_product'
import ProductTransformer from '#products/transformers/product_transformer'

export default class ProductsController {
  constructor(private productService: ProductService) {}

  async index({ response }: HttpContext) {
    const products = await this.productService.all()
    return response.json(ProductTransformer.collection(products))
  }

  async store({ request, response }: HttpContext) {
    const data = await request.validate(CreateProductValidator)
    const product = await this.productService.create(data)
    return response.json(ProductTransformer.item(product))
  }

  async show({ params, response }: HttpContext) {
    const product = await this.productService.find(params.id)
    return response.json(ProductTransformer.item(product))
  }
}
```

--------------------------------

### Disable Module Scaffolding in .adonisrc.ts

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/configuration.md

Provides an example of how to disable the AdonisJS modules package by removing its command group from the `.adonisrc.ts` configuration file. This prevents module-aware `make:*` commands from being available.

```typescript
export default defineConfig({
  commands: [
    () => import('@adonisjs/core/commands'),
    () => import('@adonisjs/lucid/commands'),
    // Remove or comment out:
    // () => import('@adonisjs-community/modules/commands'),
  ],
})
```

--------------------------------

### Create Auth Module Provider

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/module-structure-and-patterns.md

Generates a provider for bootstrapping authentication services within the auth module.

```bash
node ace make:provider auth_provider --module auth --register
```

--------------------------------

### Get Package JSON Content

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/constants-and-internals.md

Reads and parses the package.json file from the application's root directory. This utility function assumes the file exists and is valid, and will throw an error if it's missing or malformed.

```typescript
export function getPackageJson(app: ApplicationService): any {
  const packageJsonPath = path.join(
    fileURLToPath(app.appRoot), 
    'package.json'
  )
  return JSON.parse(readFileSync(packageJsonPath, 'utf-8'))
}
```

--------------------------------

### Create User and Notifications Modules

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Scaffolds the 'users' and 'notifications' modules using the Ace CLI, which is the initial step for implementing an event-driven notification system.

```bash
node ace make:module users
node ace make:module notifications
```

--------------------------------

### Project File Structure

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/INDEX.md

This snippet outlines the directory structure of the project, showing the location of the main documentation index and other key files.

```text
output/
├── INDEX.md                                    # ← You are here
├── README.md                                   # Main entry point
├── configuration.md                            # Setup & configuration
├── command-reference.md                        # Quick command lookup
├── module-structure-and-patterns.md            # Best practices & organization
├── constants-and-internals.md                  # Implementation details
└── api-reference/
    ├── configure.md                            # Installation hook
    ├── make-module-command.md                  # Module creation
    ├── modular-make-commands.md                # Extended make commands (15 commands)
    └── utils.md                                # Utility functions
```

--------------------------------

### Minimal Module Directory Structure

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/module-structure-and-patterns.md

Demonstrates a lean module structure where only necessary directories like controllers and services are created.

```text
app/
└── simple_module/
    ├── controllers/
    │   └── simple_controller.ts
    └── services/
        └── simple_service.ts
```

--------------------------------

### Create Module Test File

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Generates a unit test file for a module's service.

```bash
node ace make:test my_feature_service --module my_feature --suite unit
```

--------------------------------

### Create User Model for Auth Module

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Generate a User model with a factory for the authentication module. Remember to edit the migration to include necessary fields like email and password.

```bash
node ace make:model user --module auth --factory
```

```typescript
table.string('email').unique()
table.string('password')
table.timestamps()
```

--------------------------------

### Modular Command Implementation Pattern

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/api-reference/modular-make-commands.md

Illustrates the base class and logic for modular make commands, ensuring backward compatibility and consistency.

```typescript
export default class MModularCommand extends BaseCommand {
  @flags.string(MODULE_FLAG)
  declare module: string

  override async run() {
    // Skip custom module logic if flag not provided
    if (!this.module) {
      return super.run()
    }

    // Auto-create module if needed
    if (!checkModule(this.app, this.module)) {
      this.kernel.exec(`${COMMAND_PREFIX}:module`, [this.module])
    }

    // Use custom stubs and entity generation
    const codemods = await this.createCodemods()
    await codemods.makeUsingStub(stubsRoot, this.stubPath, {
      flags: this.parsed.flags,
      entity: this.app.generators.createEntity(this.name),
    })
  }
}
```

--------------------------------

### Batch Module Creation

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Optimizes module creation by running multiple commands in sequence for efficiency.

```bash
# Do this (faster)
node ace make:module users
node ace make:module products
node ace make:module orders
```

--------------------------------

### Module Naming Conventions

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/configuration.md

Explains the conventions for module naming, including input casing, conversion to snake_case, directory creation, and alias registration.

```markdown
| Input | Directory | Alias |
|-------|-----------|-------|
| `Auth` | `/app/auth/` | `#auth/*` |
| `userManagement` | `/app/user_management/` | `#user_management/*` |
| `API-Gateway` | `/app/api_gateway/` | `#api_gateway/*` |
```

--------------------------------

### Create Admin Controllers

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Generate controllers for managing users and settings within the admin panel.

```bash
node ace make:controller users --module admin
node ace make:controller settings --module admin
```

--------------------------------

### Create API Module

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/module-structure-and-patterns.md

Generates the basic structure for an API module.

```bash
node ace make:module api
```

--------------------------------

### Displaying General Help

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/command-reference.md

Command to display the general help information for the ACE CLI, listing all available commands.

```bash
node ace --help
```

--------------------------------

### Create Controller with Specific Actions

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Generates a controller file within a module and defines specific actions for it.

```bash
node ace make:controller users_list --module users
node ace make:controller users --module users --actions index,store,show,update,destroy
```

--------------------------------

### Create user using module service in tests

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Write unit tests to verify the functionality of services from modules, such as creating a user via '#users/services/user_service'. Ensure factories like '#users/factories/user_factory' are available.

```typescript
// tests/unit/services/user_service.spec.ts
import { test } from '@japa/runner'
import UserService from '#users/services/user_service'
import { UserFactory } from '#users/factories/user_factory'

test.group('User Service', (group) => {
  test('should create user', async () => {
    const service = new UserService()
    const user = await service.create({
      email: 'test@example.com',
      password: 'secret'
    })
    assert.exists(user.id)
  })
})
```

--------------------------------

### Create Auth Module Services

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/module-structure-and-patterns.md

Generates service files for managing authentication-related logic within the auth module.

```bash
node ace make:service auth_service --module auth
```

```bash
node ace make:service password_service --module auth
```

--------------------------------

### Using Module Imports for Generated Components

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/README.md

Illustrates how to import components like controllers, services, models, and factories using the module-specific import aliases.

```typescript
import { SignInController } from '#auth/controllers/sign_in_controller'
import { AuthService } from '#auth/services/auth_service'
import { User } from '#users/models/user'
import { UserFactory } from '#users/factories/user_factory'
```

--------------------------------

### Create Admin Models and Controller

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Generate models, factories, and controllers for the admin module. Ensure the migration includes a 'role' field for access control.

```bash
node ace make:model admin --module admin --factory --controller
```

--------------------------------

### Generate Module Providers

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/api-reference/modular-make-commands.md

Use the `make:provider` command to create a new service provider within a module. This command allows for optional registration and environment-specific configurations.

```bash
node ace make:provider <name> --module <moduleName> [--register] [--environments <env1,env2>]
```

--------------------------------

### Create Module Structure

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Scaffolds the basic file structure for a new reusable module, including services and exceptions.

```bash
node ace make:module my_feature
node ace make:service my_feature_service --module my_feature
node ace make:exception my_feature_exception --module my_feature
```

--------------------------------

### Product Service Implementation

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Provides business logic for interacting with the Product model, including methods for fetching all products, creating a new product, and finding a product by ID.

```typescript
import Product from '#products/models/product'

export default class ProductService {
  async all() {
    return Product.all()
  }

  async create(data: any) {
    return Product.create(data)
  }

  async find(id: number) {
    return Product.find(id)
  }
}
```

--------------------------------

### Service for Reusable Logic

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/module-structure-and-patterns.md

Illustrates the best practice of using services for reusable logic, contrasting it with duplicating logic in controllers.

```typescript
// ✓ Good: Reusable service
export default class EmailService {
  send(email: string, subject: string, body: string) {}
}

// ✗ Avoid: Logic duplicated in controllers
export default class UsersController {
  async store() {
    // Email sending logic here (duplicated in other controllers)
  }
}
```

--------------------------------

### Create Auth Module Events and Listeners

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/module-structure-and-patterns.md

Generates event and listener files for handling user authentication lifecycle events within the auth module.

```bash
node ace make:event user_logged_in --module auth
```

```bash
node ace make:listener on_user_logged_in --module auth --event user_logged_in
```

```bash
node ace make:event user_logged_out --module auth
```

--------------------------------

### Importing Core Packages

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/module-structure-and-patterns.md

Illustrates importing core AdonisJS framework packages for dependency injection and routing, as well as Lucid ORM and VineJS validation.

```typescript
// AdonisJS framework imports
import { inject } from '@adonisjs/core/container'
import { Router } from '@adonisjs/core/http'

// Database
import { BaseModel } from '@adonisjs/lucid/orm'

// Validation
import vine from '@vinejs/vine'
```

--------------------------------

### Generate test file for a different module and suite

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/api-reference/modular-make-commands.md

Creates a test file within a specified module and assigns it to a particular test suite, demonstrating multi-module support.

```bash
node ace make:test create_user --module users --suite=functional
```

--------------------------------

### Verify Ace command help

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Check the help documentation for an Ace command to understand its options and usage.

```bash
node ace make:controller --help
```

--------------------------------

### Create Authentication Middleware

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Generate middleware for verifying authentication status on protected routes.

```bash
node ace make:middleware verify_auth --module auth --stack router
```

--------------------------------

### Combine Model and Factory Creation

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Generates both a model and its corresponding factory in a single command for streamlined development.

```bash
# Single command with options
node ace make:model user --module users --factory
```

--------------------------------

### Index Commands for Build

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/constants-and-internals.md

Use this command during the build process to generate an index file for all command classes. This ensures commands are correctly exported and discoverable.

```bash
adonis-kit index build/commands
```

--------------------------------

### View package.json imports

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Inspect the 'imports' section of your package.json file to see how modules are configured.

```bash
cat package.json | grep -A 5 '"imports"'
```

--------------------------------

### Create Test File

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/command-reference.md

Generates a new test file. It supports specifying a module and a test suite, automatically selecting the suite if only one exists or prompting if multiple are available.

```bash
node ace make:test <name> [--module <moduleName>] [--suite <suiteName>]
```

--------------------------------

### Create and prompt for provider registration

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/api-reference/modular-make-commands.md

Creates a new provider and prompts the user for registration in the .adonisrc.ts file.

```bash
node ace make:provider auth_provider --module auth
```

--------------------------------

### Create Admin Views

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Generates the necessary view files for an admin section within a specified module.

```bash
node ace make:view layout --module admin
node ace make:view dashboard --module admin
node ace make:view users --module admin
```

--------------------------------

### Create and Register Middleware

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/README.md

Use this command to create a new middleware and automatically register it in your `.adonisrc.ts` file with the router stack.

```bash
node ace make:middleware auth_check --module auth --stack router
```

--------------------------------

### Generate test file with interactive suite selection

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/api-reference/modular-make-commands.md

Creates a test file within a specified module and interactively selects the test suite if multiple exist.

```bash
node ace make:test auth_controller --module auth
```

--------------------------------

### Create an HTTP Controller

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/command-reference.md

Generates an HTTP controller, either globally or within a specific module. It can also create multiple controller actions simultaneously.

```bash
node ace make:controller <name> [--module <moduleName>] [--actions <actions>]
```

--------------------------------

### Build Project

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/constants-and-internals.md

Execute the build script to compile TypeScript code, lint the project, and prepare it for publishing. This command orchestrates the entire build pipeline.

```bash
npm run build
```

--------------------------------

### Create Authentication Exceptions

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Generate custom exception classes for handling specific authentication errors like invalid credentials or user not found.

```bash
node ace make:exception invalid_credentials --module auth
node ace make:exception user_not_found --module auth
```

--------------------------------

### Modular Make Command Pattern

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/api-reference/modular-make-commands.md

Use the `--module` or `-m` flag to specify the target module for artifact creation. If the module does not exist, it will be automatically created.

```bash
node ace make:<artifact> <name> --module <moduleName>
node ace make:<artifact> <name> -m <moduleName>
```

--------------------------------

### Create Missing Module

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Solution for the 'Module Doesn't Exist' error: creates the module if it hasn't been registered.

```bash
node ace make:module users
```

--------------------------------

### Create Auth Module with User Model

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/module-structure-and-patterns.md

Generates an authentication module along with a custom user model, its factory, and controller.

```bash
node ace make:model user --module auth --factory --controller
```

--------------------------------

### Generate Users Module with Events

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/module-structure-and-patterns.md

Uses the Ace CLI to scaffold a new module named 'users', including a model, service, and event.

```bash
node ace make:module users
node ace make:model user --module users
node ace make:service user_service --module users
node ace make:event user_created --module users
```

--------------------------------

### Define Admin Routes

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Sets up routes for the admin section, applying a prefix and middleware.

```typescript
router.group(() => {
  router.get('/', [AdminDashboardController, 'show'])
  router.resource('users', AdminUsersController)
}).prefix('/admin').middleware(['admin_only'])
```

--------------------------------

### Generate test file with specified suite

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/api-reference/modular-make-commands.md

Creates a test file within a specified module and assigns it to a particular test suite.

```bash
node ace make:test auth_service --module auth --suite=unit
```

--------------------------------

### Create Module Service

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Generates a service file within a specific module to encapsulate business logic.

```bash
node ace make:service user_service --module users
```

--------------------------------

### Create API Module Tests

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/module-structure-and-patterns.md

Generates functional test files for listing and creating posts within the API module.

```bash
node ace make:test list_posts --module api --suite functional
```

```bash
node ace make:test create_post --module api --suite functional
```

--------------------------------

### Create Product Transformer

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Generate a transformer class for formatting product API responses within the 'products' module.

```bash
node ace make:transformer product_transformer --module products
```

--------------------------------

### Create Product Model Factory

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Generate a factory for the 'Product' model within the 'products' module, which is useful for seeding data and writing tests.

```bash
node ace make:factory product --module products
```

--------------------------------

### Test module import paths

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Use Node.js's 'node -e' to test importing artifacts directly from a module, like '#users/models/user'.

```bash
node -e "import('#users/models/user').then(m => console.log(m))"
```

--------------------------------

### Create a Service Class

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/command-reference.md

Generates a service class intended for encapsulating business logic. Services can be created globally or within a specified module.

```bash
node ace make:service <name> [--module <moduleName>]
```

--------------------------------

### Test Specific Module

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/module-structure-and-patterns.md

Shows how to run tests filtered by module name and how to generate unit tests for module services.

```bash
# Run tests for specific module
npm test -- --grep "users"

# Test module services
node ace make:test user_service --module users --suite unit
```

--------------------------------

### Displaying Help for Missing Command/Name

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/command-reference.md

Shows the help output displayed when a required command or name argument is missing.

```bash
node ace make:module
```

```bash
node ace make:controller
```

--------------------------------

### Scaffolding a Complete REST Resource

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/module-structure-and-patterns.md

A sequence of Ace CLI commands to scaffold a full RESTful resource, including module, model, factory, controller, services, validators, transformers, and tests.

```bash
# 1. Create module
node ace make:module users

# 2. Create model with factory and controller
node ace make:model user --module users --factory --controller

# 3. Create services
node ace make:service user_service --module users
node ace make:service password_service --module users

# 4. Create validators
node ace make:validator create_user --module users
node ace make:validator update_user --module users

# 5. Create transformers
node ace make:transformer user_transformer --module users

# 6. Create tests
node ace make:test users_controller --module users --suite functional
node ace make:test user_service --module users --suite unit
```

--------------------------------

### Create API Module Services

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/module-structure-and-patterns.md

Generates service files for managing post and comment data within the API module.

```bash
node ace make:service post_service --module api
```

```bash
node ace make:service comment_service --module api
```

--------------------------------

### Create Admin Module

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Use the AdonisJS CLI to generate a new module for managing administrative functionalities.

```bash
node ace make:module admin
```

--------------------------------

### Directory Structure Overview

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/README.md

This illustrates the typical directory organization for projects using the AdonisJS Community Modules package.

```text
output/
├── README.md                              # This file
├── configuration.md                       # Configuration reference
└── api-reference/
    ├── configure.md                       # Package configuration hook
    ├── make-module-command.md             # Module creation command
    ├── modular-make-commands.md           # Extended make:* commands
    └── utils.md                           # Utility functions
```

--------------------------------

### Auto-register provider for all environments

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/api-reference/modular-make-commands.md

Creates a provider and automatically registers it for all specified environments in the .adonisrc.ts file.

```bash
node ace make:provider payment_provider --module billing --register --environments=web,console
```

--------------------------------

### Create API Module Models and Relationships

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/module-structure-and-patterns.md

Generates model files for posts and comments within the API module, including factories and controllers.

```bash
node ace make:model post --module api --factory --controller
```

```bash
node ace make:model comment --module api --factory --controller
```

--------------------------------

### Create Authentication Validators

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Generate validators for login credentials and user registration to ensure data integrity.

```bash
node ace make:validator login_credentials --module auth
node ace make:validator register_user --module auth
```

--------------------------------

### Module Flag Usage (Short Form)

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/command-reference.md

Illustrates the short form (-m) of the --module flag, available on most commands but not on 'make:model' or 'make:factory' due to flag conflicts.

```bash
node ace make:controller users -m auth
```

--------------------------------

### Module Flag Syntax - Short Form

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/README.md

Illustrates the short-form syntax for the `--module` flag, which can be used with some Ace commands for module specification.

```bash
# Short form (unavailable on some commands with conflicting flags)
node ace make:controller sign_in -m auth
```

--------------------------------

### Create Product Validators

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/usage-examples-and-recipes.md

Generate validator classes for creating and updating product data within the 'products' module.

```bash
node ace make:validator create_product --module products
node ace make:validator update_product --module products
```

--------------------------------

### Test Suite Storage Structure

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/module-structure-and-patterns.md

Illustrates how tests are organized within unit and functional directories, independent of module structure.

```text
tests/
├── unit/
│   ├── services/
│   │   └── auth_service.spec.ts
│   └── utils/
│       └── password.spec.ts
└── functional/
    ├── auth/
    │   └── sign_in.spec.ts
    └── users/
        └── create_user.spec.ts
```

--------------------------------

### Create HTTP Controller in a Module

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/api-reference/modular-make-commands.md

Generates an HTTP controller within a specified module. The controller will be placed in the module's `controllers` directory. If the module does not exist, it will be created.

```bash
node ace make:controller users_controller
node ace make:controller sign_in --module auth
node ace make:controller posts --module blog --actions=index,store,show,update,destroy
```

--------------------------------

### Create a Model Factory

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/command-reference.md

Generates a model factory, which is useful for creating test data. You can specify the model name, the module it belongs to, and the number of factories to create.

```bash
node ace make:factory <modelName> [--module <moduleName>] [--count <number>]
```

--------------------------------

### Create an Event Listener

Source: https://github.com/adonisjs-community/modules/blob/main/_autodocs/command-reference.md

Generates an event listener for handling specific events. This command can optionally create the associated event if it doesn't exist and can be scoped to a module.

```bash
node ace make:listener <name> [--module <moduleName>] [--event <eventName>]
```