{"id":13991707,"url":"https://github.com/Yomguithereal/kotatsu","last_synced_at":"2025-07-22T14:31:52.364Z","repository":{"id":49161923,"uuid":"48513944","full_name":"Yomguithereal/kotatsu","owner":"Yomguithereal","description":"Straightforward command line tool to setup a development environment for modern JavaScript.","archived":false,"fork":false,"pushed_at":"2022-10-11T20:18:40.000Z","size":1079,"stargazers_count":260,"open_issues_count":15,"forks_count":11,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-11-24T02:06:02.658Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"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/Yomguithereal.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-12-23T22:37:39.000Z","updated_at":"2024-09-12T14:12:03.000Z","dependencies_parsed_at":"2023-01-20T05:32:34.130Z","dependency_job_id":null,"html_url":"https://github.com/Yomguithereal/kotatsu","commit_stats":null,"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yomguithereal%2Fkotatsu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yomguithereal%2Fkotatsu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yomguithereal%2Fkotatsu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yomguithereal%2Fkotatsu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Yomguithereal","download_url":"https://codeload.github.com/Yomguithereal/kotatsu/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227123934,"owners_count":17734226,"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-08-09T14:01:32.491Z","updated_at":"2024-11-29T12:30:38.265Z","avatar_url":"https://github.com/Yomguithereal.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","HTML/CSS Tools and Frameworks","Tools"],"sub_categories":["Mesh networks"],"readme":"# kotatsu\n\n**kotatsu** is a straightforward CLI tool aiming either at running node.js scripts or serving JavaScript/TypeScript web applications in a modern environment (modules, ES2015, [Hot Module Replacement](https://webpack.github.io/docs/hot-module-replacement.html), etc.).\n\nIts goal is to relieve developers from the really heavy stack that we now face on a daily basis when working with modern JavaScript.\n\nThe idea is to let developers new to the stack forget about it as long as they can while enabling seasoned developers to setup their environment very fast and to start customizing the stack progressively only when this is really needed.\n\nTypical use cases for **kotatsu** are hot-reloaded [express](http://expressjs.com/) APIs written in ES2015, hot-reloaded [React](https://facebook.github.io/react/) or [deku](http://dekujs.github.io/deku/) applications etc. Check the [use cases](#use-cases) for a quick glance of what can be achieved.\n\nNote that **kotatsu** currently uses [webpack](https://webpack.github.io/docs/) under the hood to perform its magic.\n\n## Summary\n\n* [Installation](#installation)\n* [Usage](#usage)\n* [Package Config](#package-config)\n* [Typescript](#typescript)\n* [Style](#style)\n* [JSON and YML](#json-and-yaml)\n* [Use Cases](#use-cases)\n  * [Interval](#interval)\n  * [Express](#express)\n  * [Deku](#deku)\n  * [React](#react)\n* [Node API](#node-api)\n  * [start](#start)\n  * [serve](#serve)\n  * [monitor](#monitor)\n  * [run](#run)\n  * [build](#build)\n* [What on earth is a kotatsu?](#explanation)\n* [Inspiration](#inspiration)\n* [License](#license)\n\n## Installation\n\nKotatsu can be installed globally (you should avoid this!) or within your node.js project using npm:\n\n```bash\n# Within your project\nnpm install --save-dev kotatsu\n\n# Globally:\n[sudo] npm install -g kotatsu\n```\n\n## Usage\n\n```\nUsage: kotatsu \u003ccommand\u003e {options} [entry]\n\nCommands:\n  cli.js start     Start a node.js script.\n  cli.js serve     Serve a client-side application.\n  cli.js monitor   Monitor a terminating node.js script.\n  cli.js run       Run the given node.js script.\n  cli.js build     Build your code for client or server.\n  cli.js scaffold  Scaffold some typical boilerplate files.\n\nOptions:\n  -c, --config            Optional webpack config that will be merged with kotatsu's one (useful if\n                          you need specific loaders).\n  -d, --devtool           Webpack devtool spec to use to compute source maps.               [string]\n  -m, --mount-node        Id of the mount node in the generated HMTL index.[string] [default: \"app\"]\n  -o, --output            Output path (either directory or filename).                       [string]\n  -p, --port              Port that the server should listen to.                     [default: 3000]\n  -s, --source-maps       Should source maps be computed for easier debugging?\n                                                                           [boolean] [default: true]\n      --cors              Should the server allow CORS?                    [boolean] [default: true]\n      --index             Path to a custom HMTL index file. Will default to `./index.html` if\n                          present.                                                          [string]\n      --jsx               Does your code uses JSX syntax?                 [boolean] [default: false]\n      --pragma            JSX pragma.                                                       [string]\n      --sass              Whether to transpile scss files (requires `sass` or `node-sass`).\n                                                                          [boolean] [default: false]\n      --typescript, --ts  Whether to support TypeScript (requires `typescript`). Enabled by default\n                          if target entry has .ts or .tsx extension.      [boolean] [default: false]\n      --open              Whether to open your browser on the served application.\n                                                                          [boolean] [default: false]\n      --presets           Babel presets separated by a comma (example:\n                          @babel/preset-stage-2,@babel/preset-react).                       [string]\n      --production        Whether to build for production (minify + define).\n                                                                          [boolean] [default: false]\n      --progress          Should it display the compilation's progress?   [boolean] [default: false]\n      --proxy             Proxy information (example: --proxy /api http://localhost:4000)   [string]\n      --public            Mounting a path to a public folder (example: --public /data ./src/data).\n                          Can be used several times. Works with directories and single files.\n                                                                                            [string]\n  -r, --html5-routing     Whether to enable HTML5 routing, i.e. redirect every unknown url on the\n                          index page to avoid reload issues.              [boolean] [default: false]\n      --quiet             Disable logs.                                   [boolean] [default: false]\n      --version           Show version number                                              [boolean]\n  -h, --help              Show help                                                        [boolean]\n\nExamples:\n  kotatsu start script.js                           Launching the given script with HMR.\n  kotatsu start -c webpack.config.js script.js      Using a specific webpack config.\n  kotatsu start --no-source-maps script.js          Disabling source maps.\n  kotatsu start script.js -- --path test.js         Passing arguments to the script.\n\n  kotatsu serve entry.js                            Serving the given app.\n  kotatsu serve --jsx entry.jsx                     Serving the given app with JSX code.\n  kotatsu serve --port 8000 entry.jsx               Serving the app on a different port.\n  kotatsu serve --proxy /api http://localhost:4000  Proxying an API.\n  kotatsu serve --public /data ./src/data           Serving local static files.\n  kotatsu serve --sass entry.js                     Supporting SASS stylesheets.\n  kotatsu serve --typescript entry.ts               Serving a TypeScript app.\n\n  kotatsu build server entry.js -o ./               Build the given server script.\n  kotatsu build client --production entry.js -o ./  Build the given client app for production.\n\n  kotatsu scaffold index.html                       Dump a boilerplate html file in stdout.\n\n```\n\nIf this is your first time using **kotatsu**, you should really check the use cases below to see how it could fit your workflow.\n\n## Package config\n\nIf you don't want to repeat yourself in your npm scripts know that you can use the `kotatsu` key of your project's `package.json` to keep a global configuration for the CLI:\n\n```json\n{\n  \"scripts\": {\n    \"dev\": \"kotatsu serve ./entry.js\"\n  },\n  \"kotatsu\": {\n    \"progress\": true,\n    \"public\": [\"/data\", \"./src/data\"]\n  }\n}\n```\n\n## TypeScript\n\n**kotatsu** supports TypeScript out of the box. If you want to use TypeScript in your project, just ensure you have a valid `tsconfig.json` file and that you have installed the `typescript` dependencies.\n\nIf your entry does not have the `.ts` or `.tsx` extension you will need to use the `--typescript` flag else everything should work automatically.\n\n## Style\n\n**kotatsu** lets you import CSS files out of the box. If you need to import SCSS files, you can use the `--sass` flag but be sure to install `sass` (or `node-sass`) for it to work.\n\n## JSON and YAML\n\nJSON and YAML imports are automatically dealt with.\n\n## Use cases\n\n### Interval\n\nThis example does not really serve a real-life purpose but merely shows you how to hot-reload a very simple node.js script.\n\nThe idea here is to create a script that will continuously print a required string into the console every 2 seconds:\n\n**1. Creating the necessary files**\n\n```js\n// file: interval.js\nvar string = require('./string.js');\n\nsetInterval(function() {\n  console.log(string);\n}, 2000);\n\n// Here is the twist: whenever the `string` dependency is updated, we will swap it:\nif (module.hot) {\n  module.hot.accept('./string.js', function() {\n    string = require('./string.js');\n  });\n}\n```\n\n```js\n// file: string.js\nmodule.exports = 'ping';\n```\n\n**2. Using kotatsu to start the script**\n\n```bash\nkotatsu start interval.js\n```\n\nNow the script will start and you should see it logging `ping` into the console every two seconds.\n\nNow edit the `string.js` file and the script will automatically update and log the new exported value of the file.\n\n**3. Let's use the same script in the browser**\n\nYou would rather run this script in the browser?\n\n```js\nkotatsu serve interval.js\n```\n\nNow go to `localhost:3000` and you should be able to observe the same kind of results in the console.\n\n**Remarks**\n\nThis example serves another purposes: showing you that **kotatsu** is meant to be used on long-running scripts such as servers or UIs. If what you need is to code a terminating script, check the `monitor` command instead.\n\nIf you need more information about `module.hot` and Hot Module Replacement (HMR), go check webpack's [docs](https://webpack.github.io/docs/hot-module-replacement.html) on the subject.\n\n### Express\n\nLet's setup a very simple hot-reloaded express app:\n\n**1. Installing necessary dependencies**\n\n```bash\nnpm i --save express\nnpm i --save-dev kotatsu\n```\n\n**2. Creating our app**\n\n```js\n// file: app.js\nvar express = require('express');\n\nvar app = express();\n\napp.get('/', function(req, res) {\n  return res.send('Hello World!');\n});\n\nmodule.exports = app;\n```\n\n**3. Creating our startup script**\n\n```js\n// file: start.js\nvar app = require('./app.js'),\n    http = require('http');\n\nvar server = http.createServer(app);\n\nserver.listen(3000);\n\nif (module.hot) {\n\n  // This will handle HMR and reload the server\n  module.hot.accept('./app.js', function() {\n    server.removeListener('request', app);\n    app = require('./app.js');\n    server.on('request', app);\n    console.log('Server reloaded!');\n  });\n}\n```\n\n**4. Using kotatsu**\n\nLaunching our app with HMR so we can work comfortably.\n\n```bash\nkotatsu start ./start.js\n```\n\nYou can now edit the express app live and it will automatically update without having to reload the script.\n\n### Deku\n\n**1. Installing necessary dependencies**\n\n```bash\nnpm i --save deku\nnpm i --save-dev kotatsu\n```\n\n**2. Creating our main component**\n\n```jsx\n// file: App.jsx\nimport {element} from 'deku';\n\nexport default function App() {\n  return \u003cdiv\u003eHello World!\u003c/div\u003e;\n}\n```\n\n**3. Creating our application's entry**\n\n```jsx\n// file: main.jsx\nimport {dom, element} from 'deku';\nimport InitalApp from './App.jsx';\n\nconst mountNode = document.getElementById('app'),\n      render = dom.createRenderer(mountNode);\n\nfunction refresh(Component) {\n  render(\u003cComponent /\u003e);\n}\nrefresh(InitalApp);\n\n// Let's handle our code's updates\nif (module.hot) {\n  module.hot.accept('./App.jsx', function() {\n    const NextApp = require('./App.jsx');\n    refresh(NextApp);\n  });\n}\n```\n\n**4. Using kotatsu**\n\nNow let's run a server to host our app:\n\n```bash\nkotatsu serve --jsx --pragma element main.jsx\n```\n\nNote that **kotatsu** will serve for you a HTML index file looking quite like this:\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n  \u003chead\u003e\n    \u003ctitle\u003ekotatsu\u003c/title\u003e\n  \u003c/head\u003e\n  \u003cbody\u003e\n    \u003cdiv id=\"app\"\u003e\u003c/div\u003e\n    \u003cscript type=\"text/javascript\" src=\"/build/bundle.js\"\u003e\u003c/script\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\nIf you need a custom one, just use the `--index` argument.\n\nNow visit `localhost:3000` and you are ready to develop.\n\n### React\n\nReact is a bit more tricky because we need to install a Babel 6 preset (`react-hmre`) to handle hot-loading.\n\n**1. Installing necessary dependencies**\n\n```bash\nnpm i --save react react-dom\nnpm i --save-dev kotatsu babel-preset-react babel-preset-react-hmre\n```\n\n**2. Creating our main component**\n\n```jsx\n// file: App.jsx\nimport React, {Component} from 'react';\n\nexport default class App extends Component {\n  render() {\n    return \u003cdiv\u003eHello World!\u003c/div\u003e;\n  }\n}\n```\n\n**3. Creating our application's entry**\n\n```jsx\n// file: main.jsx\nimport React from 'react';\nimport {render} from 'react-dom';\nimport App from './App.jsx';\n\nconst mountNode = document.getElementById('app');\n\nrender(\u003cApp /\u003e, mountNode);\n```\n\n**4. Using kotatsu**\n\nNow let's run a server to host our app:\n\n```bash\nkotatsu serve --jsx ./main.jsx\n```\n\nNote that **kotatsu** will serve for you a HTML index file looking quite like this:\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n  \u003chead\u003e\n    \u003ctitle\u003ekotatsu\u003c/title\u003e\n  \u003c/head\u003e\n  \u003cbody\u003e\n    \u003cdiv id=\"app\"\u003e\u003c/div\u003e\n    \u003cscript type=\"text/javascript\" src=\"/build/bundle.js\"\u003e\u003c/script\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\nIf you need a custom one, just use the `--index` argument.\n\nNow visit `localhost:3000` and you are ready to develop.\n\n## Node API\n\n```js\nvar kotatsu = require('kotatsu');\n```\n\nEvery method of the library uses the same configuration object (similar to the CLI arguments):\n\n*required*\n\n* **entry** *string*: Path towards the entry.\n\n*optional*\n\n* **args** *array*: array of arguments to pass to the child script.\n* **cwd** *string* [`process.cwd()`]: current working directory.\n* **config** *object*: a webpack config object.\n* **cors** *boolean* [`true`]: should the server allow CORS?\n* **devtool** *string*: a webpack devtool [spec](https://webpack.github.io/docs/configuration.html#devtool).\n* **index** *string*: path of the HTML index file to serve.\n* **jsx** *boolean* [`false`]: should we handle JSX?\n* **mountNode** *string* [`'app'`]: id of the mount node in the generated HTML index file.\n* **open** *boolean* [`false`]: Whether to open the app in you web browser as soon as served.\n* **output** *string* [`.kotatsu`]: path of the built file.\n* **port** *integer* [`3000`]: port that the server should listen to.\n* **pragma** *string*: custom JSX pragma.\n* **presets** *array*: Babel 6 presets to apply.\n* **production** *boolan*: Whether to build for production, i.e. minify output and define `NODE_ENV` as `production`.\n* **progress** *boolean* [`false`]: should the compiler display a progress bar?\n* **proxy** *array*: proxy information.\n* **quiet** *boolean* [`false`]: if true, will disable all console logs.\n* **server** *function*: function called with the express app in case you want to apply custom middlewares etc.\n* **sourceMaps** *boolean* [`true`]: should it compute source maps?\n\n### start\n\n```js\nvar watcher = kotatsu.start({\n  entry: 'script.js',\n  ...\n})\n```\n\n### serve\n\n```js\nvar server = kotatsu.serve({\n  entry: 'script.js',\n  ...\n})\n```\n\n### monitor\n\n```js\nvar watcher = kotatsu.monitor({\n  entry: 'script.js',\n  ...\n})\n```\n\n### run\n\n```js\nkotatsu.run({\n  entry: 'script.js',\n  ...\n});\n```\n\n### build\n\n```js\n// side can be either 'front' or 'back'\nkotatsu.build(side, {\n  entry: 'script.js',\n  ...\n}, callback);\n```\n\n\u003ch2 id=\"explanation\"\u003eWhat on earth is a kotatsu?\u003c/h2\u003e\n\nA [kotatsu](https://en.wikipedia.org/wiki/Kotatsu) is a low Japanase table covered by a heavy blanket with an underneath heat source that keeps you warm in the cold season.\n\n## Inspiration\n\n**kotatsu** is widely inspired by the following modules:\n\n- [webpack-hot-middleware](https://github.com/glenjamin/webpack-hot-middleware) by [@glenjamin](https://github.com/glenjamin).\n- [nodemon](https://github.com/remy/nodemon) by [@remy](https://github.com/remy).\n\n## License\n\n[MIT](LICENSE.txt)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FYomguithereal%2Fkotatsu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FYomguithereal%2Fkotatsu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FYomguithereal%2Fkotatsu/lists"}