Nextcloud Impl App Scaffold

nextcloud-impl-app-scaffold

Quick Reference

App Directory Layout

myapp/
├── appinfo/
│   ├── info.xml              # App manifest (REQUIRED)
│   └── routes.php            # Route definitions
├── lib/
│   ├── AppInfo/
│   │   └── Application.php   # Bootstrap entry point (IBootstrap)
│   ├── Controller/            # HTTP controllers
│   ├── Service/               # Business logic layer
│   ├── Db/                    # Entity classes and mappers
│   ├── Listener/              # Event listeners
│   ├── Middleware/             # Request middleware
│   ├── Migration/             # Database migrations
│   └── Command/               # OCC CLI commands
├── src/                       # Vue.js frontend source
│   ├── main.js
│   ├── App.vue
│   └── components/
├── css/                       # Stylesheets (CSS/SCSS)
├── img/
│   └── app.svg               # App icon (used as navigation icon)
├── js/                        # Compiled JS output (generated)
├── templates/                 # PHP templates
│   └── main.php
├── tests/                     # PHPUnit tests
├── l10n/                      # Translation files
├── webpack.config.js
├── package.json
├── composer.json
└── LICENSE

info.xml Required Fields

| Field | Constraint | |-------|-----------| | id | Lowercase ASCII + underscore only, MUST match app directory name | | name | Human-readable app name | | summary | Short description for app store listing | | description | Full description, supports Markdown via ` | | version | Semantic versioning (no build metadata) | | licence | SPDX identifier (AGPL-3.0-or-later, MIT, etc.) | | author | Developer name, optional mail and homepage attributes | | namespace | PascalCase, maps to OCA\{Namespace}\ PHP namespace | | category | One of: customization, files, games, integration, monitoring, multimedia, office, organization, security, social, tools | | dependencies/nextcloud | BOTH min-version AND max-version` required |

info.xml Optional Fields

| Field | Purpose | |-------|---------| | bugs | Issue tracker URL | | repository | Source code URL (with type attribute) | | website | Project homepage | | screenshot | App store screenshot (HTTPS required), optional small-thumbnail | | documentation | Child elements: user, admin, developer | | navigations/navigation | Top-level navigation entry | | background-jobs/job | Cron job class registrations | | repair-steps | Install/post-migration/uninstall repair steps | | commands/command | OCC CLI command registrations | | settings | Admin/personal settings page classes | | activity | Activity app integration (settings + providers) |

Deprecated info.xml Fields (NEVER Use)

These fields cause app store validation failure: standalone, default_enable, shipped, public, remote, requiremin, requiremax

Namespace to File Path Mapping

| info.xml ` | PHP Class | File Path | |------------------------|-----------|-----------| | MyApp | OCA\MyApp\AppInfo\Application | lib/AppInfo/Application.php | | MyApp | OCA\MyApp\Controller\PageController | lib/Controller/PageController.php | | MyApp | OCA\MyApp\Service\ItemService | lib/Service/ItemService.php | | MyApp | OCA\MyApp\Db\ItemMapper | lib/Db/ItemMapper.php | | MyApp | OCA\MyApp\Listener\MyListener | lib/Listener/MyListener.php | | MyApp | OCA\MyApp\Migration\Version1000Date | lib/Migration/Version1000Date.php` |

IBootstrap Lifecycle

| Phase | Method | When Called | Rules | |-------|--------|------------|-------| | 1 | register(IRegistrationContext $context) | Early, before all apps loaded | ONLY use $context API methods. NEVER query services. | | 2 | boot(IBootContext $context) | After ALL apps completed register() | All services available. Use $context->injectFn() for DI. |

Valid Category Values

customization | files | games | integration | monitoring | multimedia | office | organization | security | social | tools

---

Critical Warnings

ALWAYS include ` in info.xml -- the autoloader and DI container depend on it to map OCA\{Namespace}\* to the lib/` directory.

ALWAYS set both min-version and max-version in `` -- both are required for app store validation.

ALWAYS implement IBootstrap in Application.php for NC 28+ apps -- legacy constructor-based service resolution is deprecated.

ALWAYS use register() for event listeners, middleware, and service aliases -- these are lazily resolved.

ALWAYS place Application.php at lib/AppInfo/Application.php -- Nextcloud expects this exact path.

ALWAYS use the app.svg file in img/ as the app icon -- Nextcloud uses it automatically for navigation and favicons.

NEVER query services or resolve dependencies in register() -- other apps may not have completed their registration yet.

NEVER put business logic in Application.php -- keep it in Service/ classes. Application.php handles only registration and boot wiring.

NEVER use database.xml for new apps -- use PHP migration classes in lib/Migration/ instead.

NEVER use deprecated requiremin/requiremax -- use ``.

NEVER include sensitive data (API keys, passwords) in info.xml -- it is publicly readable.

NEVER omit the id field or use characters other than lowercase ASCII and underscores.

---

Essential Patterns

Pattern 1: Minimal info.xml

    myapp
    My Application
    Short description for app listing
    Full description with **Markdown** support
    1.0.0
    AGPL-3.0-or-later
    Developer Name
    MyApp
    tools
    https://github.com/org/myapp/issues
    
        
        
    

Pattern 2: Application.php with IBootstrap

registerEventListener(
            BeforeUserDeletedEvent::class,
            UserDeletedListener::class
        );

        // Middleware
        $context->registerMiddleware(AuthMiddleware::class);

        // Interface binding (only when auto-wiring is insufficient)
        $context->registerServiceAlias(IMyInterface::class, MyImplementation::class);
    }

    public function boot(IBootContext $context): void {
        // Post-registration initialization
        // All services from all apps are now available
        $context->injectFn(function (IFooManager $manager) {
            $manager->registerProvider(MyProvider::class);
        });
    }
}

Pattern 3: Navigation Entry in info.xml

    
        My App
        myapp.page.index
        app.svg
        10
    

The route value uses the format {appid}.{controller}.{method} -- it MUST match a route defined in appinfo/routes.php.

Pattern 4: Minimal routes.php

 [
        ['name' => 'page#index', 'url' => '/', 'verb' => 'GET'],
    ],
];

Pattern 5: Minimal PHP Template

Pattern 6: App Generator

Use the official Nextcloud app generator to scaffold a new app:

URL: https://apps.nextcloud.com/developer/apps/generate

This generates a downloadable skeleton with correct directory structure, info.xml, Application.php, basic controller, routes, and build configuration. It does NOT publish to the app store.

---

Decision Tree: Starting a New App

Need a new Nextcloud app?
├── Use the app generator → https://apps.nextcloud.com/developer/apps/generate
│   └── Download and customize the skeleton
├── OR create manually:
│   ├── 1. Create appinfo/info.xml with ALL required fields
│   ├── 2. Create lib/AppInfo/Application.php implementing IBootstrap
│   ├── 3. Create appinfo/routes.php with at least one route
│   ├── 4. Create lib/Controller/ with your first controller
│   ├── 5. Create templates/main.php for the page template
│   └── 6. Place app.svg in img/ for the app icon
│
├── Need a navigation entry?
│   └── Add  to info.xml with route matching routes.php
│
├── Need background jobs?
│   └── Add  to info.xml + create Job class in lib/Cron/
│
├── Need database tables?
│   └── Create migration class in lib/Migration/ (NEVER use database.xml)
│
├── Need admin settings?
│   └── Add  to info.xml + create Settings class in lib/Settings/
│
└── Need OCC commands?
    └── Add  to info.xml + create Command class in lib/Command/

---

Bootstrap Sequence (NC 28+)

1. Nextcloud scans enabled apps for lib/AppInfo/Application.php
2. Apps implementing IBootstrap have register() called (ordered by app dependencies)
3. App load groups processed (filesystem, session, etc.) in priority order
4. All Application classes fully instantiated
5. All boot() methods called -- all prior registrations are guaranteed complete
6. Request routing begins

---

Reference Links

• [references/methods.md](references/methods.md) -- info.xml fields, Application.php API, namespace mapping
• [references/examples.md](references/examples.md) -- Complete info.xml, Application.php, directory structure
• [references/anti-patterns.md](references/anti-patterns.md) -- Scaffold mistakes

Official Sources

• https://docs.nextcloud.com/server/latest/developermanual/appdevelopment/info.html
• https://docs.nextcloud.com/server/latest/developermanual/appdevelopment/bootstrap.html
• https://docs.nextcloud.com/server/latest/developermanual/appdevelopment/intro.html
• https://docs.nextcloud.com/server/latest/developermanual/basics/dependencyinjection.html
• https://apps.nextcloud.com/developer/apps/generate

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Impertio-Studio
• Source: Impertio-Studio/Nextcloud-Claude-Skill-Package
• License: MIT

Install and usage instructions live in the source repository linked above.