From aa231b37bdfcc88ab49cb120e4c55118961d7011 Mon Sep 17 00:00:00 2001 From: Alexandre St-Laurent Date: Sat, 8 Jul 2023 23:18:34 -0400 Subject: [PATCH 1/4] vite configuration --- docs/09-routing.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/docs/09-routing.md b/docs/09-routing.md index 8e77244..ac3102b 100644 --- a/docs/09-routing.md +++ b/docs/09-routing.md @@ -408,6 +408,63 @@ We can reference the stylesheet and javascript file in our views as follows: ``` +### Vite config to build the package assets + +Sometimes we want to build the assets using a bundler like Webpack or Vite. + +The latest versions of Laravel switched from Webpack to Vite, and it would be nice to use the same bundler for the package +to support all the hot reload and dev features of Vite. + +To do that we need to add Javascript packages using NPM. + +1. If you don't have a package.json file already, run the `npm init -y` command to create one. +2. Install Vite and the laravel plugin `npm install -D vite laravel-vite-plugin`. +3. Create the same structure for the resources as a Laravel website. +4. Then create a vite.config.js + +vite.config.js file content + +```js +import { defineConfig } from 'vite'; +import laravel from 'laravel-vite-plugin'; + +export default defineConfig({ + plugins: [ + laravel({ + hotFile: 'public/vendor/blogpackage/blogpackage.hot', // Most important lines + buildDirectory: 'vendor/blogpackage', // Most important lines + input: ['resources/css/app.css', 'resources/js/app.js'], + refresh: true, + }), + ], +}); +``` + +Then you can use it like this in a blade template. + +```php +{{ Vite::useHotFile('vendor/blogpackage/blogpackage.hot') + ->useBuildDirectory("vendor/blogpackage") + ->withEntryPoints(['resources/css/app.css', 'resources/js/app.js']) }} +``` + +This will then let us use the Vite dev server in a local project when developing the package. +We can also build the assets using Vite for production. + +**For development, we will need to create a symlink of the public/vendor/blogpackage folder** + +Example of a symlink command `mklink /J .\public\vendor\blogpackage .\vendor\johndoe\blogpackage\public\vendor\blogpackage` + +**For production, we will need to publish the assets** + +Add this to your ServiceProvider + +```php +$this->publishes([ + __DIR__.'/../public/vendor/blogpackage' => public_path('vendor/blogpackage'), +], 'assets'); +``` + ## Testing Routes Let’s verify that we can indeed create a post, show a post and show all posts with our provided routes, views, and controllers. From 576d2741ebd97faf8fdbb1b32358cd84ac1fcd60 Mon Sep 17 00:00:00 2001 From: Alexandre St-Laurent Date: Sat, 8 Jul 2023 23:23:13 -0400 Subject: [PATCH 2/4] added the npm scripts for Vite --- docs/09-routing.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/09-routing.md b/docs/09-routing.md index ac3102b..fe4c17f 100644 --- a/docs/09-routing.md +++ b/docs/09-routing.md @@ -440,6 +440,23 @@ export default defineConfig({ }); ``` +package.json + +```json +{ + "private": true, + "type": "module", + "scripts": { + "dev": "vite", + "build": "vite build" + }, + "devDependencies": { + "laravel-vite-plugin": "^0.7.8", + "vite": "^4.3.9" + } +} +``` + Then you can use it like this in a blade template. ```php @@ -455,6 +472,8 @@ We can also build the assets using Vite for production. Example of a symlink command `mklink /J .\public\vendor\blogpackage .\vendor\johndoe\blogpackage\public\vendor\blogpackage` +And start the dev server of both projects, the laravel app and the package. + **For production, we will need to publish the assets** Add this to your ServiceProvider From e4f93f5c70d05264e0eba28004507a2a8f1c1d90 Mon Sep 17 00:00:00 2001 From: Alexandre St-Laurent Date: Sat, 29 Jul 2023 23:04:02 -0400 Subject: [PATCH 3/4] created section 16 assets --- docs/09-routing.md | 115 ------------------------------------------ docs/16-assets.md | 122 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 122 insertions(+), 115 deletions(-) create mode 100644 docs/16-assets.md diff --git a/docs/09-routing.md b/docs/09-routing.md index fe4c17f..8daad11 100644 --- a/docs/09-routing.md +++ b/docs/09-routing.md @@ -369,121 +369,6 @@ php artisan vendor:publish --provider="JohnDoe\BlogPackage\BlogPackageServicePro Be aware that the end user needs to update the namespaces of the published component class and update the `render()` method to reference the Blade components of the Laravel application directly, instead of referencing the package namespace. Additionally, the Blade component no longer has to be namespaced since it was published to the Laravel application itself. -## Assets - -You'll likely want to include a CSS and javascript file when you're adding views to your package. - -### Creating an 'assets' Directory - -If you want to use a CSS stylesheet or include a javascript file in your views, create an `assets` directory in the `resources/` folder. Since we might include several stylesheets or javascript files, let's create **two subfolders**: `css` and `js` to store these files, respectively. A convention is to name the main javascript file `app.js` and the main stylesheet `app.css`. - -### Customizable Assets - -Just like the views, we can let our users customize the assets if they want. First, we'll determine where we'll export the assets in the `boot()` method of our service provider under the 'assets' key in a 'blogpackage' directory in the public path of the end user's Laravel app: - -```php title="BlogPackageServiceProvider.php" -app->runningInConsole()) { - // Publish assets - $this->publishes([ - __DIR__.'/../resources/assets' => public_path('blogpackage'), - ], 'assets'); - -} -``` - -The assets can then be exported by users of our package using: - -``` -php artisan vendor:publish --provider="JohnDoe\BlogPackage\BlogPackageServiceProvider" --tag="assets" -``` - -### Referencing Assets - -We can reference the stylesheet and javascript file in our views as follows: - -```html - - -``` - -### Vite config to build the package assets - -Sometimes we want to build the assets using a bundler like Webpack or Vite. - -The latest versions of Laravel switched from Webpack to Vite, and it would be nice to use the same bundler for the package -to support all the hot reload and dev features of Vite. - -To do that we need to add Javascript packages using NPM. - -1. If you don't have a package.json file already, run the `npm init -y` command to create one. -2. Install Vite and the laravel plugin `npm install -D vite laravel-vite-plugin`. -3. Create the same structure for the resources as a Laravel website. -4. Then create a vite.config.js - -vite.config.js file content - -```js -import { defineConfig } from 'vite'; -import laravel from 'laravel-vite-plugin'; - -export default defineConfig({ - plugins: [ - laravel({ - hotFile: 'public/vendor/blogpackage/blogpackage.hot', // Most important lines - buildDirectory: 'vendor/blogpackage', // Most important lines - input: ['resources/css/app.css', 'resources/js/app.js'], - refresh: true, - }), - ], -}); -``` - -package.json - -```json -{ - "private": true, - "type": "module", - "scripts": { - "dev": "vite", - "build": "vite build" - }, - "devDependencies": { - "laravel-vite-plugin": "^0.7.8", - "vite": "^4.3.9" - } -} -``` - -Then you can use it like this in a blade template. - -```php -{{ Vite::useHotFile('vendor/blogpackage/blogpackage.hot') - ->useBuildDirectory("vendor/blogpackage") - ->withEntryPoints(['resources/css/app.css', 'resources/js/app.js']) }} -``` - -This will then let us use the Vite dev server in a local project when developing the package. -We can also build the assets using Vite for production. - -**For development, we will need to create a symlink of the public/vendor/blogpackage folder** - -Example of a symlink command `mklink /J .\public\vendor\blogpackage .\vendor\johndoe\blogpackage\public\vendor\blogpackage` - -And start the dev server of both projects, the laravel app and the package. - -**For production, we will need to publish the assets** - -Add this to your ServiceProvider - -```php -$this->publishes([ - __DIR__.'/../public/vendor/blogpackage' => public_path('vendor/blogpackage'), -], 'assets'); -``` - ## Testing Routes Let’s verify that we can indeed create a post, show a post and show all posts with our provided routes, views, and controllers. diff --git a/docs/16-assets.md b/docs/16-assets.md new file mode 100644 index 0000000..5015577 --- /dev/null +++ b/docs/16-assets.md @@ -0,0 +1,122 @@ +--- +title: "Add and develop assets for the package" +description: "Configuration needed to publish assets with your package and how to configure Vite in your package for dev and production." +tags: ["Assets", "Vite"] +image: "https://www.laravelpackage.com/assets/pages/laravelpackage.jpeg" +date: 2023-07-29 +--- + +## Assets + +You'll likely want to include a CSS and javascript file when you're adding views to your package. + +### Creating an 'assets' Directory + +If you want to use a CSS stylesheet or include a javascript file in your views, create an `assets` directory in the `resources/` folder. Since we might include several stylesheets or javascript files, let's create **two subfolders**: `css` and `js` to store these files, respectively. A convention is to name the main javascript file `app.js` and the main stylesheet `app.css`. + +### Customizable Assets + +Just like the views, we can let our users customize the assets if they want. First, we'll determine where we'll export the assets in the `boot()` method of our service provider under the 'assets' key in a 'blogpackage' directory in the public path of the end user's Laravel app: + +```php title="BlogPackageServiceProvider.php" +app->runningInConsole()) { + // Publish assets + $this->publishes([ + __DIR__.'/../resources/assets' => public_path('blogpackage'), + ], 'assets'); + +} +``` + +The assets can then be exported by users of our package using: + +``` +php artisan vendor:publish --provider="JohnDoe\BlogPackage\BlogPackageServiceProvider" --tag="assets" +``` + +### Referencing Assets + +We can reference the stylesheet and javascript file in our views as follows: + +```html + + +``` + +### Vite config to build the package assets + +Sometimes we want to build the assets using a bundler like Webpack or Vite. + +The latest versions of Laravel switched from Webpack to Vite, and it would be nice to use the same bundler for the package +to support all the hot reload and dev features of Vite. + +To do that we need to add Javascript packages using NPM. + +1. If you don't have a package.json file already, run the `npm init -y` command to create one. +2. Install Vite and the laravel plugin `npm install -D vite laravel-vite-plugin`. +3. Create the same structure for the resources as a Laravel website. +4. Then create a vite.config.js + +vite.config.js file content + +```js +import { defineConfig } from 'vite'; +import laravel from 'laravel-vite-plugin'; + +export default defineConfig({ + plugins: [ + laravel({ + hotFile: 'public/vendor/blogpackage/blogpackage.hot', // Most important lines + buildDirectory: 'vendor/blogpackage', // Most important lines + input: ['resources/css/app.css', 'resources/js/app.js'], + refresh: true, + }), + ], +}); +``` + +package.json + +```json +{ + "private": true, + "type": "module", + "scripts": { + "dev": "vite", + "build": "vite build" + }, + "devDependencies": { + "laravel-vite-plugin": "^0.7.8", + "vite": "^4.3.9" + } +} +``` + +Then you can use it like this in a blade template. + +```php +{{ Vite::useHotFile('vendor/blogpackage/blogpackage.hot') + ->useBuildDirectory("vendor/blogpackage") + ->withEntryPoints(['resources/css/app.css', 'resources/js/app.js']) }} +``` + +This will then let us use the Vite dev server in a local project when developing the package. +We can also build the assets using Vite for production. + +**For development, we will need to create a symlink of the public/vendor/blogpackage folder** + +Example of a symlink command `mklink /J .\public\vendor\blogpackage .\vendor\johndoe\blogpackage\public\vendor\blogpackage` + +And start the dev server of both projects, the laravel app and the package. + +**For production, we will need to publish the assets** + +Add this to your ServiceProvider + +```php +$this->publishes([ + __DIR__.'/../public/vendor/blogpackage' => public_path('vendor/blogpackage'), +], 'assets'); +``` \ No newline at end of file From b719ed0194da0bd43c681e28a818442456442ee0 Mon Sep 17 00:00:00 2001 From: Alexandre St-Laurent Date: Sat, 29 Jul 2023 23:10:47 -0400 Subject: [PATCH 4/4] renamed assets menu label --- docs/16-assets.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/16-assets.md b/docs/16-assets.md index 5015577..91b3be7 100644 --- a/docs/16-assets.md +++ b/docs/16-assets.md @@ -1,12 +1,12 @@ --- -title: "Add and develop assets for the package" +title: "Adding assets" description: "Configuration needed to publish assets with your package and how to configure Vite in your package for dev and production." tags: ["Assets", "Vite"] image: "https://www.laravelpackage.com/assets/pages/laravelpackage.jpeg" date: 2023-07-29 --- -## Assets +# Assets You'll likely want to include a CSS and javascript file when you're adding views to your package.