README

Live Reload for TYPO3

This extension adds Livereload capabilities to your TYPO3 instance.

Installation

Install the extension via composer

composer req --dev pnodev/livereload

Note We are using Composer NPM bridge to automatically install the Node dependencies that are needed to run the livereload server. At first run, it might ask you for permission to do that. Additionally, an npm postinstall script is executed to build the server.

Include the TypoScript configuration

The extension provides a TS constant that points to a JavaScript file that has to be inserted into the frontend in order for livereload to work. It is highly recommended to only include this in development mode and to deactivate the cache while using it.

Constants.typoscript

@import 'EXT:livereload/Configuration/TypoScript/constants.typoscript'

Setup.typoscript

[applicationContext == "Development"]
   page.includeJS.livereload = {$tx_livereload.fe_bundle}
   config.no_cache = 1
[end]

Create your configuration

Add a config section to the package.json of your site package (if you are using Node to process your CSS and JavaScript, you most likely already have a package.json). By default, livereload will look for a package.json in the current working directory. But you can point it to a different place by passing a --config flag to the command:

node ./vendor/pnodev/livereload/live-reload.mjs --config ./path/to/package.json

This is where you configure rules for reloading. A valid entry consists of the path or glob to be watched (relative to you site package) and a configuration object. For each path, you at least have to specify a type. Currently, there are the following types available:

type	description
reload	Immediately reloads the entire page
stream	A stream event does not reload the page. Instead it only injects the differences into the current document (much like HMR). You can define a `files` array to only refresh specific files (like a linked JS or CSS file). If you do not specify `files`, the entire new document will be compared to the current one and only the parts that changed will be replaced.

package.json

{
    "name": "@pnodev/site-package",
    "config": {
        "livereload": {
            "host": "127.0.0.1",
            "port": "1337",
            "resources": {
                "js": {
                    "path": "./Resources/Public/Dist/main.min.js",
                    "type": "reload"
                },
                "templates": {
                    "path": "./Resources/Private/{Layouts,Partials,Templates,ContentElements}/**/*.html",
                    "type": "stream"
                },
                "css": {
                    "path": "./Resources/Public/Dist/main.min.css",
                    "type": "stream",
                    "files": [
                        "main.min.css"
                    ]
                }
            }
        }
    }
}

Usage

Livereload can be integrated in two ways:

You trigger a reload / stream by watching a file (specified in your config).
You trigger a reload by sending a request to the livereload server

The second option can be especially useful if you need for other processes to finish before looking for changes. Providing a convenient abstraction for this can be as easy as adding an npm script:

"scripts": {
  "reload": "curl -s http://localhost:1337/reload"
}

Additionally, you'll want to include the watch process that starts the livereload server in your build setup. Here is an example on how to do this:

{
   "name": "site_package",
   "scripts": {
      "watch": "node ../../vendor/pnodev/livereload/live-reload.mjs ../../../packages/site_package/livereload.config.mjs",
      "build:js": "esbuild ./Resources/Public/JavaScript/Src/main.js --outfile=./Resources/Public/JavaScript/main.js --bundle --minify --sourcemap",
      "build:css": "postcss ./Resources/Public/Css/tailwind.src.css -o ./Resources/Public/Css/main.css",
      "build": "yarn build:js && yarn build:css",
      "dev:css": "chokidar \"./Resources/Private/{Layouts,Partials,Templates}/**/*.html\" \"./tailwind.config.js\" -c \"yarn build\"",
      "dev:js": "yarn build:js --watch",
      "dev": "conc \"yarn build\" \"yarn dev:css\" \"yarn dev:js\" \"yarn watch\"",
      "reload": "curl -s http://localhost:1337/reload",
      "test": "echo \"Error: no test specified\" && exit 1"
   },
   "devDependencies": {
      "autoprefixer": "^10.4.13",
      "chokidar-cli": "^3.0.0",
      "concurrently": "^7.6.0",
      "cssnano": "^5.1.14",
      "esbuild": "^0.15.15",
      "postcss": "^8.4.19",
      "postcss-cli": "^10.0.0",
      "tailwindcss": "^3.2.4"
   }
}

The watch task starts the server and feed it the configuration file in your site package.
The dev task uses conc to start the processes for building CSS and JavaScript, as well as the watch task in parallel.

pnodev / livereload

Maintainers

Details