derver
v0.5.3
Published
Tiny Development Server for your web-applications with livereload and watchers
Downloads
71
Maintainers
Readme
Derver
Tiny Development Server for your web-applications with livereload and watchers
Features
- Very tiny (~8kb)
- Livereload
- Watch directories with callback
- CLI or JS API
- Supports Gzip or Brotli compression
- Cache control
- Supports SPA mode
CLI Usage
derver [parameters] [serve_directory]
You may use npx derver
instantly or install globally by npm install -g derver
and then use command derver
.
To serve and watching current directory just run:
derver
Server will run on http://localhost:7000 and site will be reloaded each time you change the file in the served directory.
By default server is running on localhost
and nobody can access on the website from the network. Bind server on the 0.0.0.0
interface to allow network connections:
derver --host=0.0.0.0 public
In this example, public
is a directory where are files for serving. By default it is current directory.
List of possible parameters
--host
Interface, where bind the server. Use 0.0.0.0
inside Docker container or when need network connections to your site.
Default: localhost
Example: --host=localhost
--port
Port, where bind the server. Default: 7000 Example: --port=8080
--index
Name of the root file of web directory. Webserver will lookup this file when no file specified in the requested URL. Default: index.html Example: --index=index.htm
--watch
Specify the directories for watching files changes. Each time when files modified in these directories, website will be reloaded. You may use this parameter multiple times to set more than one directory for watching. Default: watch the served directory Example: --watch=dist/public --watch=src
--no-watch
Add this parameter when you want to disable any watching and livereloading. Example: --no-watch
--compress
Will return files compressed by gzip or brotli, if client supports it. Example: --compress
--cache
Add Cache-control
header to the response with max-age
equal 31536000
(~1 year). You can specify number of seconds.
Example: --cache
Example: --cache=3600
--scroll
Restore scroll position on every reload. Number value is equal timeout before scroll restoration. Example: --scroll Example: --scroll=100
--spa
Enables SPA (Single-Page Application) mode. All requested pages will be responsed by index page in the application root, which is specified in --index
parameter.
Example: --spa
--production
Run server in production mode(really not, use at own risk). It enables --cache
, --compress
and --no-watch
parameters. Also host will set on 0.0.0.0
to handle connections from the network.
Example: --production
Javascript API
You may use Derver in the your scripts to get more power.
Install Derver as local dependency:
npm install derver
Then use derver
function from the derver
package to start the server.
import {derver} from 'derver';
derver();
By default, server will be started on http://localhost:7000 and serve public
directory in your workdir.
Configuration
You may set configuration object as a parameter of the derver
function. Below you find all possible options:
dir
string|boolean
Directory which contains files for serving. If nothing set in watch
option, it will be watching for changes also. When it is false
- no files would be serving, only middlewares will work.
Default: public
Example: dir: 'public' Example: dir: false
host
string
Interface, where bind the server. Use 0.0.0.0
inside docker or when need network connections to your site.
Default: localhost
Example: host: 'localhost'
port
number
Port, where bind the server.
Default: 7000
Example: port: 8080
index
string
Name of the root file of web directory. Webserver will lookup this file when no file specified in the requested URL.
Default: index.html
Example: index: 'index.htm'
compress
boolean
Will return files compressed by gzip or brotli, if client supports it.
Default: false
Example: compress: true
cache
boolean|number
Add Cache-control
header to the response with max-age
equal 31536000
(~1 year). You can specify number of seconds.
Default: false
Example: cache: true
Example: cache: 3600
spa
boolean
Enables SPA (Single-Page Application) mode. All requested pages will be responced by index page in the application root, which is specified in index
option.
Default: false
Example: spa: true
watch
string|array of string
Specify the directories for watching filechanges. Each time when files modified in theese directories, website will be reloaded and onwatch
callback will be run. By default will be watched directory defined in dir
option.
Default: null
Example: watch: ['dist/public','src']
remote
boolean|string
Enables remote control listener. See Remote control
Default: false
Example: remote: true
Example: remote: "my_dev_server"
parseJson
boolean
When incoming request sent with type application/json
Derver will parse its body and put object in request.body
.
Default: true
Example: parseJson: true
preserveScroll
boolean|number
Restore scroll position on every reload. Number value is equal timeout before scroll restoration.
Default: false
Example: preserveScroll: true
Example: preserveScroll: 100
banner
boolean
Show or not the banner in console when server starts.
Default: true
Example: banner: false
log
boolean
Show or not file requests in console
Default: true
Example: log: false
onwatch
function
This function will be called when any file changes in watched directories.
Default: null
Example: onwatch: (liverload,watchitem)=>{if(watchitem == 'src') livereload.prevent()})
onwatch
-callback arguments
Callback signature: (livereload,watchitem,filename,eventname)
livereload
It is object with following methods:
livereload.prevent()
- Will stop sheduled livereload action for this watch event.livereload.reload()
- Run each time you want to reload page in the browser.livereload.console(message)
- Send amessage
to the browser console.livereload.error(message,[header])
- Show error modal on client.
watchitem
It is a string with directory name where were fired filechange event. It is same string as you specified in watch
option(or in dir
option, if watch
not set).
filename
Full path of changed file (unstable)
eventname
What exactly happened with modified file.
Using Middlewares
You may use any common middleware(like Express middlewares) to add additional functionality for you server. derver()
function returns the object with methods:
sub
- run callback to register middlewares for specified subpathuse
- run middleware for all HTTP methodsget
- run middleware for GET method onlypost
- run middleware for POST method only- ...actually you can write any HTTP method here
derver()
.use(middleware1)
.get('/api',middleware2)
.put('/clear',middleware3,middleware4)
Pattern
If first argument for these methods is a pattern of the URL, middleware will run only if request's URL is matched with its path.
The pattern may looks like /foo
of /foo/bar
. If no pattern provided, middleware will run on each request.
Pattern also may have a parameters /user/:name
and when URL will be /user/bob
or /user/alex
you can get the value(alex or bob) from request.params.name
property.
derver()
.use('/user/:name',middleware)
Writing middleware function
The middleware functions gets three arguments - common Node's request
,response
objects and next
function, which will run next middleware. If your middleware doesn't response on request, you must run next()
or request never will be ended.
Lets see an example for client and API middleware:
function myLogMiddleware(req,resp,next){
console.log('Current URL is: ' + req.url);
next();
}
function myHelloMiddleware(req,resp){
resp.send('Hello, '+req.params.name);
}
derver()
.use(myLogMiddleware)
.get('/hello/:name',myHelloMiddleware)
Additional data from incoming request extension
The request
argument is Node's http.IncomingMessage object. But it is expanded with few useful data:
path
- pathname of current URLsearch
- query params as a stringquery
- query params as an objecthost
- host from header(including port)hostname
- host from header(without port)port
- port from header
If request sent with type application/json
you will get the parsed object from request.body
. To avoid this, set parseJson
option to false
;
Send JSON object in responce
Method responce.send(message)
will send content of message with status code 200. If message
is a simple object, Derver will automaticly stringify it and send to client with Content-type: application/json
header.
Nested middlewares
In case you need to run middlewares which are situated under specified sub path use .sub()
method.
derver()
.sub('/api',(app)=>
// will run on every request starting with '/api/...'
app.use(myLogMiddleware);
// will run when URL will be '/api/hello/bob'
app.get('/hello/bob',myHelloMiddleware);
app.sub('/users',(app)=>{
// will run when URL will be '/api/users/add'
app.post('/add',myUserAddMiddleware);
})
})
Remote control
There is a way to perform some actions in currently opened browser windows. For example you want to reload page from external script.
import {createRemote} from 'derver';
// Create remote object with parameters of running server
const remote = createRemote({host:'localhost',port:7000}); // there are defaults, may be dropped
// Also you can call `createRemote('my_dev_server)` with server ID specified in remote option.
// Reload page in all opened browser windows
remote.reload();
// Send some text in the browser console
remote.console('Hello!');
// Show modal with error message
remote.error('Error happened! Fix it as soon as possible!','Error header');
Note: don't forget to enable remote
option in Derver's configuration
How livereload works
When you changes file in the watching directory, server will send command to the client side to reload current page. It is musthave feature when you developing web-application and want to see changes immediately.
Livereload made with Server Sent Events API. It is perfect feature for one-way communication server with client based only on http protocol. It is why Derver is so tiny, no need to implement websocket communication as others known servers do.
Some JavaScript code for livereload will be added before </body>
element inside each requested html
file.