Skip to content

Commit e2e7499

Browse files
jiripudiljiripudil
committed
Contributted
1 parent c410f66 commit e2e7499

57 files changed

Lines changed: 302 additions & 267 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.docs/README.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Webpack
2+
3+
## Contents
4+
5+
- [Setup](#setup)
6+
- [Usage](#usage)
7+
8+
## Setup
9+
10+
```bash
11+
composer require contributte/webpack
12+
```
13+
14+
## Usage
15+
16+
Register the extension in your config file, and configure it. The two `build` options are mandatory:
17+
18+
```yaml
19+
extensions:
20+
webpack: Contributte\Webpack\DI\WebpackExtension(%debugMode%, %consoleMode%)
21+
22+
webpack:
23+
build:
24+
directory: %wwwDir%/dist
25+
publicPath: dist/
26+
```
27+
28+
29+
Now you can use the `{webpack}` macro in your templates. It automatically expands the provided asset name to the full path as configured:
30+
31+
```html
32+
<script src="{webpack app.js}"></script>
33+
```
34+
35+
36+
### webpack-dev-server integration
37+
38+
You might want to use the Webpack's [dev server](https://www.npmjs.com/package/webpack-dev-server) to facilitate the development of client-side assets. But maybe once you're done with the client-side, you would like to build the back-end without having to start up the dev server.
39+
40+
This package effectively solves this problem: it automatically serves assets from the dev server if available (i.e. it responds within a specified timeout), and falls back to the build directory otherwise. All you have to do is configure the dev server URL. The dev server is enabled automatically in debug mode; you can override this setting via `enabled` option:
41+
42+
```yaml
43+
webpack:
44+
devServer:
45+
enabled: %debugMode% # default
46+
url: http://localhost:3000
47+
timeout: 0.1 # (seconds) default
48+
```
49+
50+
#### Ignored assets
51+
52+
You can also configure a set of asset names that should be ignored (i.e. resolved to an empty data URI) if the dev-server is available. This can be helpful e.g. if you use [`style-loader`](https://www.npmjs.com/package/style-loader) in development which does not emit any CSS files.
53+
54+
```yaml
55+
webpack:
56+
devServer:
57+
ignoredAssets:
58+
- main.css
59+
```
60+
61+
#### Public URL (e.g. Docker usage)
62+
63+
Dev-server might have different URLs for different access points. For example, when running in Docker Compose setup, the Nette application accesses it via the internal Docker network, while you access it in the browser via the exposed port. For this, you can set up a different `publicUrl`.
64+
65+
```yaml
66+
webpack:
67+
devServer:
68+
url: http://webpack-dev-server:3000 # URL over internal Docker network
69+
publicUrl: http://localhost:3030 # exposed port from the dev-server container
70+
```
71+
72+
73+
### Asset resolvers and manifest file
74+
75+
You might want to include the Webpack's asset hash in its file name for assets caching (and automatic cache busting in new releases) in the user agent. But how do you reference the asset files in your code if their names are dynamic?
76+
77+
This package comes to the rescue. You can employ the [`webpack-manifest-plugin`](https://www.npmjs.com/package/webpack-manifest-plugin) or some similar plugin (see below) to produce a manifest file, and then configure the adapter to use it:
78+
79+
```yaml
80+
webpack:
81+
manifest:
82+
name: manifest.json
83+
```
84+
85+
This way, you can keep using the original asset names, and they get expanded automatically following the resolutions from the manifest file.
86+
87+
This package automatically optimizes this in production environment by loading the manifest file in compile time.
88+
89+
90+
#### Manifest mappers
91+
92+
By default, the manifest loader supports the aforementioned `webpack-manifest-plugin`. If you use a different plugin that produces the manifest in a different format, you can implement and configure a mapper for it. This package comes bundled with a mapper for the [`assets-webpack-plugin`](https://www.npmjs.com/package/assets-webpack-plugin):
93+
94+
```yaml
95+
webpack:
96+
manifest:
97+
name: manifest.json
98+
mapper: Contributte\Webpack\Manifest\Mapper\AssetsWebpackPluginMapper
99+
```
100+
101+
You can also implement your own mapper, simply extend `Contributte\Webpack\Manifest\ManifestMapper` and implement its `map()` method. It takes the parsed JSON content of the manifest file and is expected to return a flat array mapping asset names to file names.
102+
103+
104+
### Debugger
105+
106+
In development environment, this package registers its own debug bar panel into Tracy, giving you the overview of
107+
108+
- what assets have been resolved and how;
109+
- the path from where the assets are served;
110+
- whether the dev server is enabled and available.
111+
112+
![Debug bar panel](debug_panel.png)

doc/debug_panel.png renamed to .docs/debug_panel.png

File renamed without changes.

‎README.md‎

Lines changed: 31 additions & 109 deletions
Original file line numberDiff line numberDiff line change
@@ -1,119 +1,41 @@
1-
# Oops/WebpackNetteAdapter
1+
# Webpack
22

3-
[![Build Status](https://img.shields.io/github/workflow/status/o2ps/WebpackNetteAdapter/Test)](https://github.com/o2ps/WebpackNetteAdapter/actions?query=workflow%3ATest)
4-
[![Code Coverage](https://img.shields.io/codecov/c/github/o2ps/WebpackNetteAdapter.svg)](https://codecov.io/gh/o2ps/WebpackNetteAdapter)
5-
[![Downloads this Month](https://img.shields.io/packagist/dm/oops/webpack-nette-adapter.svg)](https://packagist.org/packages/oops/webpack-nette-adapter)
6-
[![Latest stable](https://img.shields.io/packagist/v/oops/webpack-nette-adapter.svg)](https://packagist.org/packages/oops/webpack-nette-adapter)
7-
[![License](https://img.shields.io/packagist/l/oops/webpack-nette-adapter)](https://packagist.org/packages/oops/webpack-nette-adapter)
3+
[Webpack](https://github.com/webpack) integration into [Nette Framework](https://github.com/nette).
84

9-
WebpackNetteAdapter is a tool that helps integrate your Nette Framework application with assets built via Webpack.
5+
[![Build Status](https://img.shields.io/github/workflow/status/contributte/webpack/Test)](https://github.com/contributte/webpack/actions?query=workflow%3ATest)
6+
[![Code Coverage](https://img.shields.io/codecov/c/github/contributte/webpack.svg)](https://codecov.io/gh/contributte/webpack)
7+
[![Downloads this Month](https://img.shields.io/packagist/dm/contributte/webpack.svg)](https://packagist.org/packages/contributte/webpack)
8+
[![Latest stable](https://img.shields.io/packagist/v/contributte/webpack.svg)](https://packagist.org/packages/contributte/webpack)
9+
[![License](https://img.shields.io/packagist/l/contributte/webpack)](https://packagist.org/packages/contributte/webpack)
1010

11+
## Discussion / Help
1112

12-
## Installation and requirements
13+
[![Join the chat](https://img.shields.io/gitter/room/contributte/contributte.svg?style=flat-square)](http://bit.ly/ctteg)
1314

14-
```bash
15-
$ composer require oops/webpack-nette-adapter
16-
```
15+
## Documentation
1716

18-
Oops/WebpackNetteAdapter requires PHP >= 7.4.
17+
- [Setup](.docs/README.md#setup)
18+
- [Usage](.docs/README.md#usage)
1919

20+
## Version
2021

21-
## Usage
22+
| State | Version | Branch | Nette | PHP |
23+
|-------------|--------------|----------|----------|----------|
24+
| stable | `^2.0` | `master` | `3.0+` | `>= 7.4` |
25+
| development | `dev-master` | `master` | `3.0+` | `>= 7.4` |
2226

23-
Register the extension in your config file, and configure it. The two `build` options are mandatory:
27+
## Maintainers
2428

25-
```yaml
26-
extensions:
27-
webpack: Oops\WebpackNetteAdapter\DI\WebpackExtension(%debugMode%, %consoleMode%)
28-
29-
webpack:
30-
build:
31-
directory: %wwwDir%/dist
32-
publicPath: dist/
33-
```
34-
35-
36-
Now you can use the `{webpack}` macro in your templates. It automatically expands the provided asset name to the full path as configured:
37-
38-
```html
39-
<script src="{webpack app.js}"></script>
40-
```
41-
42-
43-
### webpack-dev-server integration
44-
45-
You might want to use the Webpack's [dev server](https://www.npmjs.com/package/webpack-dev-server) to facilitate the development of client-side assets. But maybe once you're done with the client-side, you would like to build the back-end without having to start up the dev server.
46-
47-
WebpackNetteAdapter effectively solves this problem: it automatically serves assets from the dev server if available (i.e. it responds within a specified timeout), and falls back to the build directory otherwise. All you have to do is configure the dev server URL. The dev server is enabled automatically in debug mode; you can override this setting via `enabled` option:
48-
49-
```yaml
50-
webpack:
51-
devServer:
52-
enabled: %debugMode% # default
53-
url: http://localhost:3000
54-
timeout: 0.1 # (seconds) default
55-
```
56-
57-
#### Ignored assets
58-
59-
You can also configure a set of asset names that should be ignored (i.e. resolved to an empty data URI) if the dev-server is available. This can be helpful e.g. if you use [`style-loader`](https://www.npmjs.com/package/style-loader) in development which does not emit any CSS files.
60-
61-
```yaml
62-
webpack:
63-
devServer:
64-
ignoredAssets:
65-
- main.css
66-
```
67-
68-
#### Public URL (e.g. Docker usage)
69-
70-
Dev-server might have different URLs for different access points. For example, when running in Docker Compose setup, the Nette application accesses it via the internal Docker network, while you access it in the browser via the exposed port. For this, you can set up a different `publicUrl`.
71-
72-
```yaml
73-
webpack:
74-
devServer:
75-
url: http://webpack-dev-server:3000 # URL over internal Docker network
76-
publicUrl: http://localhost:3030 # exposed port from the dev-server container
77-
```
78-
79-
80-
### Asset resolvers and manifest file
81-
82-
You might want to include the Webpack's asset hash in its file name for assets caching (and automatic cache busting in new releases) in the user agent. But how do you reference the asset files in your code if their names are dynamic?
83-
84-
WebpackNetteAdapter comes to the rescue. You can employ the [`webpack-manifest-plugin`](https://www.npmjs.com/package/webpack-manifest-plugin) or some similar plugin (see below) to produce a manifest file, and then configure the adapter to use it:
85-
86-
```yaml
87-
webpack:
88-
manifest:
89-
name: manifest.json
90-
```
91-
92-
This way, you can keep using the original asset names, and they get expanded automatically following the resolutions from the manifest file.
93-
94-
WebpackNetteAdapter automatically optimizes this in production environment by loading the manifest file in compile time.
95-
96-
97-
#### Manifest mappers
98-
99-
By default, WebpackNetteAdapter supports the aforementioned `webpack-manifest-plugin`. If you use a different plugin that produces the manifest in a different format, you can implement and configure a mapper for it. WebpackNetteAdapter comes bundled with a mapper for the [`assets-webpack-plugin`](https://www.npmjs.com/package/assets-webpack-plugin):
100-
101-
```yaml
102-
webpack:
103-
manifest:
104-
name: manifest.json
105-
mapper: Oops\WebpackNetteAdapter\Manifest\Mapper\AssetsWebpackPluginMapper
106-
```
107-
108-
You can also implement your own mapper, simply extend `Oops\WebpackNetteAdapter\Manifest\ManifestMapper` and implement its `map()` method. It takes the parsed JSON content of the manifest file and is expected to return a flat array mapping asset names to file names.
109-
110-
111-
### Debugger
112-
113-
In development environment, WebpackNetteAdapter registers its own debug bar panel into Tracy, giving you the overview of
114-
115-
- what assets have been resolved and how;
116-
- the path from where the assets are served;
117-
- whether the dev server is enabled and available.
118-
119-
![Debug bar panel](doc/debug_panel.png)
29+
<table>
30+
<tbody>
31+
<tr>
32+
<td align="center">
33+
<a href="https://github.com/jiripudil">
34+
<img width="150" height="150" src="https://avatars1.githubusercontent.com/u/1042159?s=150&v=4">
35+
</a>
36+
<br/>
37+
<a href="https://github.com/jiripudil">Jiří Pudil</a>
38+
</td>
39+
</tr>
40+
</tbody>
41+
</table>

‎composer.json‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
{
2-
"name": "oops/webpack-nette-adapter",
3-
"description": "Webpack adapter for Nette Framework.",
2+
"name": "contributte/webpack",
3+
"description": "Webpack integration for Nette Framework.",
44
"keywords": ["nette", "webpack"],
55
"type": "library",
66
"license": "BSD-3-Clause",
7+
"homepage": "https://github.com/contributte/webpack",
78
"authors": [
89
{
910
"name": "Jiří Pudil",
@@ -13,7 +14,7 @@
1314
],
1415
"support": {
1516
"email": "me@jiripudil.cz",
16-
"issues": "https://github.com/o2ps/WebpackNetteAdapter/issues"
17+
"issues": "https://github.com/contributte/webpack/issues"
1718
},
1819
"require": {
1920
"php": ">=7.4",
@@ -35,7 +36,7 @@
3536
},
3637
"autoload": {
3738
"psr-4": {
38-
"Oops\\WebpackNetteAdapter\\": "src/"
39+
"Contributte\\Webpack\\": "src/"
3940
}
4041
},
4142
"scripts": {

‎src/AssetLocator.php‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,10 @@
22

33
declare(strict_types=1);
44

5-
namespace Oops\WebpackNetteAdapter;
5+
namespace Contributte\Webpack;
66

7-
use Oops\WebpackNetteAdapter\AssetNameResolver\AssetNameResolverInterface;
8-
use Oops\WebpackNetteAdapter\DevServer\DevServer;
7+
use Contributte\Webpack\AssetNameResolver\AssetNameResolverInterface;
8+
use Contributte\Webpack\DevServer\DevServer;
99

1010
final class AssetLocator
1111
{

‎src/AssetNameResolver/AssetNameResolverInterface.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
declare(strict_types=1);
44

5-
namespace Oops\WebpackNetteAdapter\AssetNameResolver;
5+
namespace Contributte\Webpack\AssetNameResolver;
66

77
interface AssetNameResolverInterface
88
{

‎src/AssetNameResolver/CannotResolveAssetNameException.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
declare(strict_types=1);
44

5-
namespace Oops\WebpackNetteAdapter\AssetNameResolver;
5+
namespace Contributte\Webpack\AssetNameResolver;
66

77
final class CannotResolveAssetNameException extends \RuntimeException
88
{

‎src/AssetNameResolver/DebuggerAwareAssetNameResolver.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
declare(strict_types=1);
44

5-
namespace Oops\WebpackNetteAdapter\AssetNameResolver;
5+
namespace Contributte\Webpack\AssetNameResolver;
66

77
final class DebuggerAwareAssetNameResolver implements AssetNameResolverInterface
88
{

‎src/AssetNameResolver/IdentityAssetNameResolver.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
declare(strict_types=1);
44

5-
namespace Oops\WebpackNetteAdapter\AssetNameResolver;
5+
namespace Contributte\Webpack\AssetNameResolver;
66

77
final class IdentityAssetNameResolver implements AssetNameResolverInterface
88
{

‎src/AssetNameResolver/ManifestAssetNameResolver.php‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,10 @@
22

33
declare(strict_types=1);
44

5-
namespace Oops\WebpackNetteAdapter\AssetNameResolver;
5+
namespace Contributte\Webpack\AssetNameResolver;
66

7-
use Oops\WebpackNetteAdapter\Manifest\CannotLoadManifestException;
8-
use Oops\WebpackNetteAdapter\Manifest\ManifestLoader;
7+
use Contributte\Webpack\Manifest\CannotLoadManifestException;
8+
use Contributte\Webpack\Manifest\ManifestLoader;
99

1010
final class ManifestAssetNameResolver implements AssetNameResolverInterface
1111
{

0 commit comments

Comments
 (0)