{"id":17325185,"url":"https://github.com/mistic/static-fs","last_synced_at":"2025-04-14T16:56:20.129Z","repository":{"id":35076748,"uuid":"144220773","full_name":"mistic/static-fs","owner":"mistic","description":":package: A static filesystem to bundle and read files using Node.js","archived":false,"fork":false,"pushed_at":"2023-01-06T02:00:39.000Z","size":2293,"stargazers_count":5,"open_issues_count":39,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-28T05:31:44.241Z","etag":null,"topics":["bundler","filesystem","fs","javascript","nodejs","require","static"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/static-fs","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mistic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-08-10T01:22:23.000Z","updated_at":"2023-02-04T18:19:05.000Z","dependencies_parsed_at":"2023-01-15T13:30:23.645Z","dependency_job_id":null,"html_url":"https://github.com/mistic/static-fs","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mistic%2Fstatic-fs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mistic%2Fstatic-fs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mistic%2Fstatic-fs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mistic%2Fstatic-fs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mistic","download_url":"https://codeload.github.com/mistic/static-fs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248923657,"owners_count":21183949,"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":["bundler","filesystem","fs","javascript","nodejs","require","static"],"created_at":"2024-10-15T14:12:38.048Z","updated_at":"2025-04-14T16:56:20.108Z","avatar_url":"https://github.com/mistic.png","language":"JavaScript","readme":"\u003ch1 align=\"center\"\u003e\n  Static-Fs\n\u003c/h1\u003e \n\n[![CI Build Status][ci-build-status-image]][ci-build-status-url]\n[![Commitizen Friendly][commitizen-friendly-image]][commitizen-friendly-url]\n[![NPM Version][npm-version-image]][npm-version-url]\n[![NODE Version][node-version-image]][node-version-url]\n[![David Node Deps Manager][david-node-deps-manager-image]][david-node-deps-manager-url]\n[![David Node Deps Manager Development][david-node-deps-manager-dev-image]][david-node-deps-manager-dev-url]\n[![NPM Install Size][npm-install-size-image]][npm-install-size-url]\n\n\nA static filesystem to bundle multiple files into one that are\nable to be read by Node.js through `require` or the [fs module](https://nodejs.org/api/fs.html).\n\n## Why\n\nThere are a lot of use cases which require shipping `node_modules` along with the distribution in order to achieve a `zero install` workflow for our end users. Given the nature of node_modules, this directory ends up containing a magnitude of files resulting in a degraded experience, especially on Windows environments (bad performance unzipping, bad performance through an installer,  max file path length, etc).\n\nThat was the first motivation and the main use case for the static filesystem: \nallow to bundle all the files from the `node_modules` during the build process into a single file \nand then, at runtime, force node to first look into that statically generated \nfilesystem when searching for a file and only look in the real filesystem \nin case the file is not found on the static one.\n\nWhile the main use case is the above there could be others like for example shipping almost \nevery product file in a statically generated filesystem so we can make the product structure \nsimple and transparent for the end user. The only thing to keep in mind is `that \ntool was designed to be used during a build process` under certain assumptions.\n\n## Features\n\n- Pack multiple files into a single one called static filesystem that would \nmount relatively to the parent directory where it is generated\n\n- Patches `require`, `fs`, `process` and `child_process` to be able to read \nfrom the static filesystem\n\n- Run multiple static filesystem per application\n\n- One single build step tool that works out of the box\n\n## Getting Started\n\nRemember, that this is a development tool intended to be used during your \nbuild process, so install it as `development dependency` and run it as \na final step once your build produce the raw build artifacts.\n\n### Install\n\n```\nnpm install --save-dev static-fs\n```\n\n### Usage\n\n**Generate a static filesystem volume**\n```javascript\n// example_build_step.js\n\nconst { generateStaticFsVolume } = require('static-fs');\nconst { resolve } = require('path');\n\n// one example of a dependency to delete files in bulk, you can use any other\nconst del = require('del');\n\n(async () =\u003e {\n  const mountRoot = resolve('.'), \n    folderToAdd = resolve('node_modules'),\n    entryPoint = resolve('index.js');\n  \n  // Generate a static filesystem volume\n  const addedFiles = await generateStaticFsVolume(\n    mountRoot,\n    [\n      folderToAdd\n    ],\n    [\n      entryPoint\n    ]\n    //, [] -\u003e exclusions are optional and equal to [] by default\n  );\n  \n  // Delete all the files bundled into the static filesystem volume\n  await del(addedFiles, { force: true });\n})()\n```\n\n**Run your app**\n\nJust run `node index.js` (which was the entryPoint we assume for that example) \nin the root of your distributable app folder and everything should work. \n\n## API\n\n### `async generateStaticFsVolume(mountRootDir, foldersToAdd, appEntryPointsToPatch, exclusions)`\n\nAn async function that would take care of generating the static filesystem \nconsidering that the root path to mount it would be `mountRootDir`, the content \nwould be created according `foldersToAdd`, your application entry points \nwould be automatically patched according `appEntryPointsToPatch` so node can read \nfrom the generated static filesystem, and any path (folder or file) listed on `exclusions`\nwould be discarded.\n\n\u003e NOTE: After running that function a folder called `.static_fs` would be \ncreated inside `mountRootDir` with `static_fs_volume.sfsv`, `static_fs_index.json`, `static_fs_manifest.json` and \n`static_fs_runtime.js`.\n\n**Params** \n\n- `mountRootDir: string`: Path for the root path of the contained files \ninto that static filesystem instance\n\n- `foldersToAdd: string[]`: List of paths of folders containing the files \nto bundle inside that static filesystem instance. Could not be the same as \n`mountRootDir`.\n\n- `appEntryPointsToPatch: string[]`: List of paths for the application entry points \nto be patched in order to read from the static filesystem.\n\n- `exclusions: string[] = []`: List of paths that would explicit not be included by \nthe static filesystem during the generation phase. The paths on this list could \nbe a folder or a single file and they should be absolute resolved against \n`mountRootDir` otherwise the function would throw an error. In case the path \nis a folder, the entire folder and children would be also excluded. \n\n**Returns**\n\nAn `string[]` containing the paths of each file and base folder \nthat was added into this static filesystem instance. \n\n## Known Limitations\n\nA little set of things are not supported by the static filesystem. They can \nbe summarised in the following list:\n\n- `.node` native modules files are not supported inside the static filesystem. \nThey will be excluded during the generation phase and are expected to be present \nin the original location on the real filesystem.\n\n- Like the above mentioned `.node` files, every other platform-specific files that\nrequires to be compiled, processed or any other changing operation during runtime are \nnot supported inside the static filesystem. As they won't be excluded automatically, \nthey should not be included inside the static filesystem during the generation phase. \n\n- While this is more a design choice than a limitation we choose to list it \nhere: any write operation is not supported against the static filesystem during runtime.\nIt would mimic the file state at the time it was generated. In case a write operation is requested \nusing write flags through a method that supports it like `open` or `createReadStream` an \nerror will be thrown. If the write operation is requested through any other write only method the \nfile will be written at the given path and the Static-Fs will start returning the content of that file\ninstead of the one inside the respective volume which previously have the file bundled.\n\nLet us know if you found other unknown limitations [opening an issue](https://github.com/mistic/static-fs/issues/new).\n\n## Contributing\n\nIf you would like to contribute, please read [CONTRIBUTING](CONTRIBUTING.md).\n\n## License\n\nSee [LICENSE](LICENSE).\n\n## Thanks\n\nOur thanks can be read at [THANKS](THANKS.md).\n  \n[ci-build-status-image]: https://github.com/mistic/static-fs/workflows/CI.CD/badge.svg?branch=master \n[ci-build-status-url]: https://github.com/mistic/static-fs/actions?query=workflow%3ACI.CD+branch%3Amaster\n[commitizen-friendly-image]: https://img.shields.io/badge/commitizen-friendly-brightgreen.svg\n[commitizen-friendly-url]: http://commitizen.github.io/cz-cli\n[npm-version-image]: https://img.shields.io/npm/v/static-fs\n[npm-version-url]: https://www.npmjs.com/package/static-fs\n[node-version-image]: https://img.shields.io/node/v/static-fs\n[node-version-url]: https://nodejs.org/download/release/v10.19.0\n[david-node-deps-manager-image]: https://img.shields.io/david/mistic/static-fs\n[david-node-deps-manager-url]: https://david-dm.org/mistic/static-fs\n[david-node-deps-manager-dev-image]: https://img.shields.io/david/dev/mistic/static-fs\n[david-node-deps-manager-dev-url]: https://david-dm.org/mistic/static-fs?type=dev\n[npm-install-size-image]: https://packagephobia.now.sh/badge?p=static-fs\n[npm-install-size-url]: https://packagephobia.now.sh/result?p=static-fs\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmistic%2Fstatic-fs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmistic%2Fstatic-fs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmistic%2Fstatic-fs/lists"}