{"id":20372623,"url":"https://github.com/txchen/light-server","last_synced_at":"2025-04-04T23:08:39.135Z","repository":{"id":27669758,"uuid":"31155758","full_name":"txchen/light-server","owner":"txchen","description":"A lightweight cli static http server and it can watch files, execute commands and trigger livereload","archived":false,"fork":false,"pushed_at":"2022-10-24T22:56:16.000Z","size":1358,"stargazers_count":182,"open_issues_count":16,"forks_count":30,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-28T22:13:32.144Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/light-server","language":"JavaScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/txchen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-02-22T07:13:02.000Z","updated_at":"2025-02-11T15:47:57.000Z","dependencies_parsed_at":"2023-01-14T08:30:48.022Z","dependency_job_id":null,"html_url":"https://github.com/txchen/light-server","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/txchen%2Flight-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/txchen%2Flight-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/txchen%2Flight-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/txchen%2Flight-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/txchen","download_url":"https://codeload.github.com/txchen/light-server/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247261609,"owners_count":20910108,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-15T01:14:05.698Z","updated_at":"2025-04-04T23:08:39.119Z","avatar_url":"https://github.com/txchen.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# -- Deprecated --\n\nPlease use [vite](https://vitejs.dev/) instead.\n\n# light-server\n\nA lightweight cli static http server and it can watch files, execute commands and trigger livereload.\n\n## Why light-server\n\nWhen I was writing some simple static web apps, it was helpful to have some tools to serve static http, to watch files and run command, and to trigger refresh in browser.\n\nI think the scenario is not too complicated, so I don't want to use heavy tools like grunt or gulp. IMO, npm script with cli tools is already enough.\n\nHere is an [article](https://www.keithcirkel.co.uk/how-to-use-npm-as-a-build-tool/) about using npm to replace grunt/gulp, I really like it.\n\nThere are many existing tools in npm, but I could not find one to do all the things for me. Well, actually browser-sync is one, but it offers too many features I don't need, and its installation time is really, unacceptable.\n\nNot lucky enough :(\n\nThen I wrote light-server, with the following features:\n\n* A simple static http server\n* Watch files, support multiple glob expressions\n* Trigger custom command if watched files change\n* Trigger browser reload if watched files change\n* Trigger css reload without refreshing page\n* Live reload does not require any setup, and even works on smart phones\n* Auto inject client reload javascript in html, no need to manually add\n* Live reload websocket server uses the same port as http server\n* Proxy to another http server\n* Html5 history API mode for SPA\n\nAnd now my package.json is simpler and cleaner than before :)\n\n## Install\n\nlight-server has much smaller footprint, compared to browser-sync, so it is recommended to install in project level, and use it with npm script.\n\n```bash\nnpm install light-server\n```\n\nOf course, you can install it globally, too.\n\n## Usage\n\n```text\nUsage: light-server [options]\n\nOptions:\n\n  -h, --help                           output usage information\n  -V, --version                        output the version number\n  -c, --config \u003cconfigfile\u003e            read options from config file\n  -s, --serve \u003cdirectory\u003e              serve the directory as static http\n  --servePrefix \u003cprefix\u003e               virtual path prefix for static directory\n  -p, --port \u003cport\u003e                    http server port, default 4000\n  -b, --bind \u003cbind\u003e                    bind to a specific host, default 0.0.0.0\n  -w, --watchexp \u003cwatch expression\u003e    watch expression, repeatable\n  -i, --interval \u003cwatch inteval\u003e       interval in ms of watching, default 500\n  -d, --delay \u003clivereolad delay\u003e       delay in ms before triggering live reload, default 0\n  -x, --proxy \u003cupstreamurl\u003e            when file not found, proxy the request to another server\n  --proxypath \u003cproxypath\u003e              only send to proxy when path starts with this pattern, default is \"/\", repeatable\n  --no-reload                          disable live-reloading\n  -q, --quiet                          quiet mode with minimum log message\n  -o, --open [path]                    open browser automatically, optional path\n  --http2                              enable http2 tls mode\n  --historyindex \u003chistoryindex\u003e        404 fallback index path, used by SPA development\n\nExamples:\n\n  $ light-server -s . -p 7000\n  $ light-server -s dist --http2 -o\n  $ light-server -s dist --historyindex '/index.html'\n  $ light-server -s . -w \"*.js, src/** # npm run build \u0026\u0026 echo wow!\"\n  $ light-server -s . -x http://localhost:8000\n  $ light-server -s . -x http://localhost:8000 --servePrefix /assets\n  $ light-server -s . -b 10.0.0.1\n  $ light-server -x http://localhost:9999 --proxypath \"/api\" -w \"public/**\"\n  $ light-server -s static -w \"**/*.css # # reloadcss\"\n  $ light-server -c .lightserverrc\n  \u0026 light-server -s . -p 8000 -w \"src/**/*.js # npm run js # no-reload\"\n\nWatch expression syntax: \"files[,files] # [command to run] # [reload action]\"\n  3 parts delimited by #\n  1st part: files to watch, support glob format, delimited by \",\", support negate patterns (by [gaze](https://github.com/shama/gaze)).\n  2nd part: (optional) command to run, before reload\n  3rd part: (optional) reload action, default is \"reload\", also supports \"reloadcss\" or \"no-reload\" to run a command without a browser refresh\n  Examples:\n    \"**/*.js, index.html # npm run build # reload\"\n    \"*.css # # reloadcss\"\n    \"** # make\"\n    \"**/*.js # npm run build # no-reload\"\n    \"**,!logs/**\"\n```\n\nIt is quite simple, specify the folder to serve as static http, specify the files to watch, specify the command to run when watched files change, and light-server will do the job.\n\n**You don't need to add reload script into your html, light-server will inject it automatically.**\n\nYou don't need to use all the features, and that's totally ok:\n\n* You can serve http without watching files.\n* You can serve http and enable live-reload, without triggering command.\n* You can watch files and trigger command, without serving http.\n\n## Manual trigger live-reload\n\nGET or POST `http://localhost:PORT/__lightserver__/trigger`, light-server will send reload event to the browser.\n\nGET or POST `http://localhost:PORT/__lightserver__/triggercss`, light-server will send reloadcss event to the browser.\n\nIt means that it's possible to integrate other tools with light-server.\n\n## Proxy\n\nProxy feature is useful when our project is some backend language(like go, python) + static web page.\n\nFor example, a golang web app exposes REST api via \u003chttp://host/api/\u003e and server static page from \u003chttp://host/\u003e. Then, when we are writing/debugging the static pages, light-server can be helpful. We can firstly launch the whole app and listen at `http://localhost:9000`, then in another terminal window, launch light-server:\n\n```bash\n$ cd \u003cyour static pages dir\u003e\n$ light-server -s . -p 8000 -x http://localhost:9000\n```\n\nNow when you access the static pages/js/css, light-server will return it directly. And if you access something like `http://localhost:8000/v1/myapi`, light-server cannot find the resource, and will proxy the request to upstream - `http://localhost:9000/v1/myapi`, which is the golang app.\n\nThis is cool because now you can have live-reload, without changing the golang app to add some dirty hacky changes, and you don't need to change the html to inject any extra js just for development. Light-server deals with all the dirty work.\n\n## Example\n\nLet's take a look at a real example. [Riot-Hackernews](https://github.com/txchen/riot-hn) is a static web app powered by riotjs. This is its package.json:\n\n```json\n{\n  \"devDependencies\": {\n    \"browserify\": \"^8.1.3\",\n    \"light-server\": \"^1.0.0\",\n    \"minifyify\": \"^6.2.0\",\n    \"riotify\": \"^0.0.9\"\n  },\n  \"scripts\": {\n    \"build\": \"npm run build:js \u0026\u0026 npm run build:css\",\n    \"build:js\": \"browserify -t [riotify --ext html] -d src/index.js -p [minifyify --compressPath . --map index.js.map --output build/index.js.map] -o build/index.js\",\n    \"build:css\": \"cp src/main.css build/main.css\",\n    \"dev\": \"light-server -s . -p 9090 -w \\\"src/**/*.js, src/**/*.html # npm run build:js\\\" -w \\\"src/main.css # npm run build:css # reloadcss\\\"\"\n  },\n  \"dependencies\": {\n    \"riot\": \"^2.0.11\"\n  }\n}\n```\n\nThe project uses browserify and plugins to bundle the source code into a single bundle.js, it is not using css pre/post processors but for sure it could.\n\nThe build process is defined in script `build`, which is quite straightforward.\n\nDuring development, we can use `npm run dev`, which will use light-server to serve the static content, and watch the changes of any js/html files under `src` directory. When it detects file change, it would trigger build and if build pass, browser will auto reload. And light-server will watch the source css file, when it changes, trigger reloadcss, which is faster than page refresh.\n\nPlease notice that windows cannot handle single quotes well, so make sure you are using double quotes when you write complex watch expressions. Or, use the config file described below.\n\nOf course, you can also achieve that by using grunt or gulp, with more dependencies and more LOC.\n\n## Config file\n\nLight-server also supports reading options from a config file. This might be useful if the command line is too long in your package.json.\n\nTo use a config file, create a json file and use `-c/--config`. The config template is like this:\n\n```json\n{\n  \"serve\": \"src\",\n  \"servePrefix\": \"/assets\",\n  \"serveRedirect\": false,\n  \"port\": 8000,\n  \"bind\": \"localhost\",\n  \"watchexps\": [\n    \"**.js # npm run build\",\n    \"*.css # # reloadcss\"\n  ],\n  \"interval\": 500,\n  \"delay\": 0,\n  \"proxy\": \"http://localhost:9999\",\n  \"proxypaths\": [ \"/api\" ],\n  \"noReload\": false,\n  \"quiet\": false,\n  \"open\": true,\n  \"http2\": false,\n  \"historyindex\": \"/index.html\"\n}\n```\n\nYou can use comments in the json, because we love comments in json :) Also all the fields in the json are optional.\n\n[This](./examples/example1/) is an example to show how to use the config file, thanks @Scarysize for making this.\n\nThe values in the command line have higher priority than the ones in the config file.\n\n## Changelog\n\n**2020-10-16** `2.9.1`\nFix the issue that noReload cannot be turned on in config file.\n\n**2020-10-16** `2.9.0`\nUpdate localhost.crt/localhost.key, make key length to 2048.\n\n**2020-07-28** `2.8.0`\nAllow passing a path into the open option, #64.\n\n**2020-06-07** `2.7.0`\nAdd option 'serveRedirect' in rc file, #58.\n\n**2020-06-07** `2.6.5`\nUpgrade dependencies.\n\n**2019-09-14** `2.6.4`\nUpgrade dependencies. Bug fix: #54.\n\n**2019-03-30** `2.6.3`\nUpgrade dependencies. Bug fix: #49.\n\n**2019-03-30** `2.6.2`\nBug fix: #46.\n\n**2019-03-15** `2.6.1`\nBug fix: #45.\n\n**2018-10-18** `2.6.0`\nBug fix: #41. Added list dir feature for #42.\n\n**2018-05-10** `2.5.1`\nBug fix: #38.\n\n**2018-03-22** `2.5.0`\nAdd no-reload option. Thanks @gkalpak for the PR.\n\n**2018-03-21** `2.4.1`\nAdd serve prefix option. Thanks @AurelienRichez for the PR.\n\n**2018-01-31** `2.4.0`\nUse gaze instead of fs.watch, so that we can detect new file added event.\n\n**2018-01-31** `2.3.0`\nSupport multiple proxypaths in CLI and config. Upgrade deps.\n\n**2018-01-30** `2.2.2`\nAdd a default extension to static files. Thanks @sidewalksalsa for the PR.\n\n**2017-07-28** `2.2.1`\nOpen localhost in browser instead of 0.0.0.0, because 0.0.0.0 is not working on win.\n\n**2017-07-26** `2.2.0`\nAdd --proxypath. Add history fallback mode, for SPA development.\n\n**2017-07-24** `2.1.0`\nAdd -o/--open option, to open browser automatically.\n\n**2017-04-30** `2.0.2`\nChange default bind value to undefined, align with node server.listen.\n\n**2017-01-19** `2.0.0`\nBump version to 2.0.0, since 1.1.8 introduced breaking changes.\n\n**2017-01-19** `1.1.10`\n1.1.8 and 1.1.9 introduced breaking change, republish a new 1.1.x to fix.\n\n**2017-01-13** `1.1.9`\nAdd http2 mode.\n\n**2017-01-13** `1.1.8`\nMake the options in configFile, cli and default use consistent names. Thanks @pmast for the initial PR.\n\n**2016-05-30** `1.1.7`\nAdd no-reload option, thanks @Scarysize for the PR.\n\n**2016-03-10** `1.1.6`\nFix proxyUrl bug, thanks @aemkei for the PR.\n\n**2016-01-25** `1.1.5`\nAdd config file support.\n\n**2016-01-24** `1.1.4`\nImprove css reload, thanks @eliot-akira for the PR.\n\n**2016-01-22** `1.1.3`\nAdd quiet mode, thanks @eliot-akira for the PR.\n\n**2015-12-01** `1.1.2`\nImprove help message.\n\n**2015-12-01** `1.1.1`\nSet changeOrigin to true by default when creating proxy. Thanks @joelcollinsdc for reporting this issue.\n\n**2015-10-15** `1.1.0`\nNow we can use proxy without static serving. Also improve the html injecting logic\n\n**2015-10-12** `1.0.7`\nUpgrade npm dependencies\n\n**2015-07-31** `1.0.6`\nAdd bind option, by @davidmarkclements\n\n**2015-05-30** `1.0.3`\nFix typo\n\n**2015-04-16** `1.0.1`\nPrint command execution duration\n\n**2015-04-15** `1.0.0`\nNew feature: watch and reload css without refreshing page\nBreaking change: change CLI interface to support reloadcss\n\n**2015-04-12** `0.1.4`\nNew feature: proxy\n\n**2015-03-02** `0.1.3`\nAdd delay option\n\n**2015-02-28** `0.1.1`\nFirst version.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftxchen%2Flight-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftxchen%2Flight-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftxchen%2Flight-server/lists"}