README

Nutshell is a feature-rich package designed to extend Acorn for WordPress themes. It provides a flexible foundation for advanced theme development, including configuration inheritance, Sentry integration, Vite asset support, and more.

Features

Child Theme Configuration Inheritance:
- Allows child themes to override parent configuration files without directory scans.
- Uses a custom configuration repository to support unsetting and merging config values.
Vite Asset Support:
- Integrates with Vite for modern asset bundling and hot reloading.
Sentry Integration:
- Seamless error reporting via Sentry for Laravel.
Custom View Composers:
- Manual registration of view composers for fine-grained control.
Custom Console Commands:
- Register custom Artisan commands via configuration.

Requirements

PHP >= 8.1
Acorn ^4.3
Composer

Installation

Install this package with composer
```
composer require yard/nutshell
```
Ensure your project's composer.json uses PSR-4 autoloading for your theme and childtheme and remove any redundant autoloading from the theme itself.
```
"autoload": {
   "psr-4": {
   "App\\": "web/app/themes/sage/app/",
+   "ChildTheme\\App\\": "web/app/themes/child-theme/app/",
   }
},
```

Configuration

Important

After this change:

View Composers in the app/View/Composers directory will no longer be loaded automatically. To ensure they are registered, you have to configure them manually.
Console Commands in the app/Console/Commands directory will no longer be loaded automatically. To ensure they are register, you have to configure them manually.

Child Theme Setup

Create a child theme with Sage as the parent theme. See WordPress Child Themes.

Example style.css:

/**
   * Theme Name:         Sage Child Theme
   * Template:           sage
   * Theme URI:          https://www.example.com/sage-child/
   * Description:        Sage child theme
   * Version:            1.0.0
   * Author:             Example Inc.
   * Author URI:         http://www.example.com/
   * Text Domain:        sage
   * License:            MIT License
   * License URI:        https://opensource.org/licenses/MIT
   * Requires PHP:       8.1
   * Requires at least:  5.9
   */
   ```

Place your configuration files in config/ within your child theme directory. These will be merged with the parent configuration where child theme configuration takes precedence. To unset a configuration option from the parent theme in the child theme you can pass an empty array for that configuration option.

Update Acorn Bootloader
- In your theme's functions.php, use the Yard\Nutshell\bootloader() helper to bootstrap Acorn with Nutshell's enhancements.
```
-\Roots\bootloader()->boot();
+define('ACORN_BASEPATH', __DIR__);
+\Yard\Nutshell\bootloader()->boot();
```
Update app config
- In your themes `config/app.php' replace Acorn's ServiceProvider with Nutshell's ServiceProvider
```
-use Roots\Acorn\ServiceProvider;
+use Yard\Nutshell\ServiceProvider;
```

Register View Composers

Add your view composers to config/view.php under the composers key. Automatic discovery is disabled for explicit control.

-  'composers' => [],
+  'composers => [
+    'app' => App\View\Composers\App::class,
+    'comments' => App\View\Composers\Comments::class,
+    'post' => App\View\Composers\Post::class,
+  ],

Register Console Commands
- Add custom Artisan commands to config/console.php under the commands key.
```
+  'commands => [
+    'test' => App\Console\Commands\Test::class,
+  ],
```
Vite Integration
- Vite is enabled by default. Use the provided Yard\Nutshell\Assets\Vite class for asset management.
Sentry Integration
- Sentry is automatically integrated if sentry/sentry-laravel is installed and configured.

Usage

Configuration Inheritance: Any config file in your child theme's config/ directory will override the parent. Empty config files will unset the corresponding configuration.
View Composers: Register all composers manually in config/view.php.
Console Commands: Register all commands manually in config/console.php.
Vite: Use the @vite directive or helper as usual; Nutshell ensures correct asset paths.
Sentry: Errors and exceptions are reported to Sentry automatically.

yard / nutshell

Maintainers

Details