Developer guide

This page is for people who want to build against XBackBone, automate it, or contribute to the codebase. If you just want to run and use an instance, start with What is XBackBone? and the Installation guide instead.

How it is built

XBackBone is distributed as a monorepo composed of two parts:

Part	Description
core	The full XBackBone application — a Laravel + Livewire app that implements all the logic. It is published as the xbackbone/core Composer package.
app	A minimal installation skeleton (config, bootstrap and public entrypoint) that pulls xbackbone/core in as a Composer dependency.

The skeleton boots the core package and remaps its public, storage and environment paths to the skeleton root. Keeping the application logic in a versioned package means an instance can be upgraded or downgraded by simply changing the required version of xbackbone/core, without touching the rest of the deployment (see Upgrading).

The skeleton ships a console binary named xbb — the deployment-side equivalent of Laravel's artisan. When you work on the core package in isolation you use artisan directly; on a deployed app instance you use php xbb <command>.

Tech stack

• PHP 8.4+ · Laravel 13
• Livewire 4 for the reactive UI, with Tailwind CSS 4, daisyUI and Mary UI components
• Laravel Fortify for authentication, Sanctum for API tokens, Pennant for feature flags
• Scramble for auto-generated OpenAPI documentation
• Flysystem adapters for FTP/SFTP, ffmpeg and ImageMagick/GD for media previews
• Vite for asset bundling; tested with Pest, analyzed with Larastan, formatted with Pint

Core concepts

The two central concepts are users and resources. A resource represents anything that can be shared — an uploaded file (image, video, audio, PDF, text, or generic file), a paste, a shortened link, or a directory.

• Content-addressed storage. Files are stored under a fingerprint derived from their contents, so identical uploads are stored only once.
• Short codes. Each resource is exposed through a short Sqids-based code.
• Visibility & lifecycle. Resources support public/private visibility, optional password protection, and expiration.

Business logic lives in small, context-agnostic Actions (under app/Actions/) that are reused from web requests, the console and queued jobs. The user-facing UI is a set of Livewire components; storage backends are plain Flysystem disks (see Storage backends).

REST API

XBackBone exposes a versioned REST API (currently v1) for uploading and managing resources programmatically, authenticated with Sanctum bearer tokens. It is what every client integration — ShareX and friends — uses under the hood.

The controllers live under app/Http/Controllers/Api/V1/, the routes in routes/api/v1.php, and responses are shaped by Eloquent API resources in app/Http/Resources/Api/V1/. Because the schema is specific to each instance and version, every instance serves interactive, always-up-to-date OpenAPI documentation generated by Scramble at /docs/api.

For the endpoints, authentication, request fields and full response shape, see the REST API reference.

Local development

These instructions are for working on the core package in isolation. For a real deployment, use the app skeleton.

# Install dependencies
composer install
npm install

# Set up the environment
cp .env.example .env
php artisan key:generate

# Run migrations
php artisan migrate

# Start the dev servers (Vite + PHP)
npm run dev
php artisan serve

Open the app in your browser; on first run you'll be redirected to the /install wizard to create the database schema and the admin account.

Quality tooling

All three must pass before changes are merged:

php artisan test            # Pest test suite
vendor/bin/pint             # Code style (Laravel Pint)
vendor/bin/phpstan analyse  # Static analysis (Larastan)

Contributing

Contributions are welcome. Please read the project's Code of Conduct before opening an issue or pull request, and make sure the quality tooling above passes.