# Nextcloud Impl App Scaffold

> >

- **Type:** Skill
- **Install:** `agentstack add skill-impertio-studio-nextcloud-claude-skill-package-nextcloud-impl-app-scaffold`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Impertio-Studio](https://agentstack.voostack.com/s/impertio-studio)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Impertio-Studio](https://github.com/Impertio-Studio)
- **Source:** https://github.com/Impertio-Studio/Nextcloud-Claude-Skill-Package/tree/main/skills/source/nextcloud-impl/nextcloud-impl-app-scaffold

## Install

```sh
agentstack add skill-impertio-studio-nextcloud-claude-skill-package-nextcloud-impl-app-scaffold
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```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

```php
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

```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

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

### Pattern 5: Minimal PHP Template

```php

    

```

### 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/developer_manual/app_development/info.html
- https://docs.nextcloud.com/server/latest/developer_manual/app_development/bootstrap.html
- https://docs.nextcloud.com/server/latest/developer_manual/app_development/intro.html
- https://docs.nextcloud.com/server/latest/developer_manual/basics/dependency_injection.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](https://github.com/Impertio-Studio)
- **Source:** [Impertio-Studio/Nextcloud-Claude-Skill-Package](https://github.com/Impertio-Studio/Nextcloud-Claude-Skill-Package)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-impertio-studio-nextcloud-claude-skill-package-nextcloud-impl-app-scaffold
- Seller: https://agentstack.voostack.com/s/impertio-studio
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.