A friendly middleware for browser-sync to proxy files on a live server to your local filesystem.
Thanks to browser-sync, it offers file watching and live reloading (with injection wherever possible).
The primary use case for local-proxy has been to assist in the development of WordPress themes on a production site by allowing you to editing local files, and having them injected into the proxied site.
This side steps the complexities of keeping your local and remote databases and media libraries in sync, and allows you to make hot-reloaded CSS edits which are visible only to you. Mess around with your theme in private, and deploy the renovated theme when it's ready.
It's not necessary to install - you can use npx to run a 'temporary auto-installed' version:
npx @ptim/local-proxy https://example.comIt's handy to install globally so that you can use it across any of your projects:
npm install -g @ptim/local-proxy
# or
yarn global add @ptim/local-proxyIf you prefer to install locally, consider adding an entry to NPM scripts in package.json:
{
"scripts": {
"proxy": "local-proxy https://example.com"
}
}Then you can npm run proxy or yarn proxy.
The most basic use is:
cd my-wordpress-theme
local-proxy example.comBy default, local-proxy will assume that the current folder is a WordPress theme folder, and will set prefix variable accordingly, eg: wp-content/themes/my-wordpress-theme.
See #concept and #options for more info.
local-proxy does three main things:
- proxy the target site, so that
example.comis browsable on your computer aslocalhost:3000 - serve any local files that correspond to remote requests, so if you have a properly placed
style.css, then it gets served instead of the 'live' version - watch for changes to specified local files, and inject them into the page without requiring a browser refresh (when possible - there's no hot refresh here, sorry!)
The most basic example configuration might be:
{
"target": "example.com",
"prefix": "wp-content/themes/my-theme",
"files": "style.css"
}Which is interpreted as:
example.com/wp-content/themes/my-theme/style.css
^---------^ ^------------------------^ ^-------^
target prefix files
You could proxy both your plugins and themes directory like so:
{
"target": "example.com",
"prefix": "wp-content",
"files": "(themes|plugins)/**"
}This should work nicely if you run local-proxy from inside your local wp-content directory. You only need to mirror files that you actually want to override! If there's a problem finding or serving a local file, then the original, remote file will be sent to the browser instead.
Of course, this is really only useful for styling changes, because your local PHP files will never get executed on the live site!
To see the options on the fly:
local-proxy --helpPath to a JSON config file (.local-proxyrc.json is automatically found).
You can provide the URL to proxy as "target".
Options should be provided in camelCase only, eg:
{ "target": "example.com" }Path to the directory where local files are stored. Defaults to . - the current directory.
Proxy (and watch) files matching this glob pattern.
Defaults to **/*.css - any CSS file below the current directory.
Eg:
**= any file in any subdirectorydist/*.(css|js)= CSS or JS files in the dist directory
See:
- Gulp: explaining Globs
- glob-primer (we're actually using fast-glob, but this documentation is similar, and succinct)
- micromatch which does the pattern matching for fast-glob
The path components between the domain and the file(s) you want to match.
If your target file is example.com/wp-content/themes/my-theme/styles.css, then the prefix is: wp-content/themes/my-theme.
By default, local-proxy will assume that the current folder is a WordPress theme folder, and will set prefix variable accordingly, eg: wp-content/themes/my-wordpress-theme.
Auto-open in the browser. Defaults to false.
Don't auto-open in the browser Defaults to true.
Port to serve the proxied site on. Defaults to 3000.
Print extra detail in the console. Pass -v, -vv, or -vvv.
Show version number
Show help
Local-proxy prints the options it has received to the command line check to see that way that your options were parsed as you expect. Eg:
Target: https://example.com
Directory: ./
Path prefix:
Files to inject: **/*.(css|css.map)
Note: "./" means the directory from which you ran local-proxy.
It's recommended to specify a protocol (http or https) for your target URL.
- if you don't set a protocol for the target URL, http will be inferred
- if an HTTP URL is proxied, requesting https://localhost won't resolve!
Check the output on the command line:
[Browsersync] Proxying: http://example.com
Ensure that the protocol of your target url is correct. Eg:
✅ https://example.com => https://localhost ✅ http://example.com => http://localhost ❌ https://example.com => http://localhost ❌ http://example.com => https://localhost
Is the "Files to inject" config correct?
...rather than the styles being injected? In all likelihood, another file (eg *.js) is also triggering a refresh, and this other file can't be injected. If this is the case, browsersync will display something along the lines of
Files changed (2 changes buffered)
instead of:
Files changed
This is expected - self signed certificates are not implemented. Click 'Advanced' and proceed to the insecure site - YOLO!
Most likely due to a server-side redirection, like an htaccess directive to redirect a www domain to a "naked " domain.
- load the target site directly and copy the URL
yarn start <copied URL>
If this fixes the issue, update your config.
- tests!
- add a command to mirror all the files loaded by the target site
- port across to a webpack configuration