{"id":26335831,"url":"https://github.com/spinframework/spin-fileserver","last_synced_at":"2025-04-07T15:11:09.034Z","repository":{"id":38188148,"uuid":"458456140","full_name":"spinframework/spin-fileserver","owner":"spinframework","description":"A static file server implemented as a Spin component","archived":false,"fork":false,"pushed_at":"2025-03-14T15:05:58.000Z","size":287,"stargazers_count":44,"open_issues_count":7,"forks_count":29,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-03-31T14:11:51.385Z","etag":null,"topics":["fermyon","spin-wasm","webassembly"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spinframework.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-12T07:48:48.000Z","updated_at":"2025-03-14T15:06:02.000Z","dependencies_parsed_at":"2024-05-16T01:38:24.094Z","dependency_job_id":"b038445b-23d8-476c-a8b6-888e78b18abb","html_url":"https://github.com/spinframework/spin-fileserver","commit_stats":{"total_commits":71,"total_committers":16,"mean_commits":4.4375,"dds":0.8450704225352113,"last_synced_commit":"8383179e1d22a92c3f4bc583f2b2f8b125821d01"},"previous_names":["spinframework/spin-fileserver"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spinframework%2Fspin-fileserver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spinframework%2Fspin-fileserver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spinframework%2Fspin-fileserver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spinframework%2Fspin-fileserver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spinframework","download_url":"https://codeload.github.com/spinframework/spin-fileserver/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247675607,"owners_count":20977378,"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":["fermyon","spin-wasm","webassembly"],"created_at":"2025-03-16T01:05:16.984Z","updated_at":"2025-04-07T15:11:09.008Z","avatar_url":"https://github.com/spinframework.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Static file server for Spin applications\n\nA simple static file server as a [Spin](https://github.com/fermyon/spin) HTTP\ncomponent, written in Rust.\n\nThis component is now fully [componentized](https://component-model.bytecodealliance.org/) and\ncan be used with any runtime that supports `wasi:http@0.2.0-rc-2023-10-18`, such as\n[Spin 2.0](https://developer.fermyon.com/spin/install), [wasmtime](https://github.com/bytecodealliance/wasmtime)\nand [NGINX Unit](https://unit.nginx.org/).\n\n- [Building from source](#building-from-source)\n- [Testing](#testing)\n- [Using the component](#using-the-component-as-part-of-a-spin-application)\n  - [Running the file server](#running-the-file-server)\n  - [Composing with the file server](#component-composition-with-the-file-server)\n- [Configuration options](#configuration-options)\n\n## Building from source\n\nPrerequisites:\n\n- [Rust](https://www.rust-lang.org/) at [1.72+](https://www.rust-lang.org/tools/install) with the `wasm32-wasip1` target configured\n- [cargo-component](https://github.com/bytecodealliance/cargo-component)\n- [Spin v2.0](https://github.com/fermyon/spin) to run the component/examples\n\nCompiling the component:\n\n```shell\n$ cargo component build --release\n```\n\nSee the [examples](./examples) directory for examples of using and composing `spin-fileserver` with applications.\n\n## Testing\n\nPrerequisites:\n\n- [Rust](https://www.rust-lang.org/) at\n  [1.72+](https://www.rust-lang.org/tools/install) with the `wasm32-wasip1` target\n  configured\n\nRunning test cases:\n\n```shell\n$ make test\n```\n\n## Using the component as part of a Spin application\n\nThe easiest way to use this the Spin fileserver component in your application\nis to add it via its Spin template.\n\nTo create a new Spin app based on this component, run:\n\n```shell\n$ spin new -t static-fileserver\n```\n\nTo add this component to your existing Spin app, run:\n\n```shell\n$ spin add -t static-fileserver\n```\n\nIf you're looking to upgrade the version of this component in your application from one\nof the [releases](https://github.com/fermyon/spin-fileserver/releases), select the release\nand corresponding checksum and update the component's `source` in the application's `spin.toml`, e.g.:\n\n```toml\nsource = { url = \"https://github.com/fermyon/spin-fileserver/releases/download/v0.1.0/spin_static_fs.wasm\", digest = \"sha256:96c76d9af86420b39eb6cd7be5550e3cb5d4cc4de572ce0fd1f6a29471536cb4\" }\n```\n\nNext, we'll look at running the file server directly as well as using component\ncomposition to integrate this component in with your application logic.\n\n### Running the file server\n\nLet's have a look at the component definition (from [spin.toml](./spin.toml)):\n\n```toml\n[[trigger.http]]\nroute = \"/...\"\ncomponent = \"fs\"\n\n# For more on configuring a component, see: https://developer.fermyon.com/spin/writing-apps\n[component.fs]\nsource = \"target/wasm32-wasip1/release/spin_static_fs.wasm\"\nfiles = [{ source = \"\", destination = \"/\" }]\n[component.fs.build]\ncommand = \"make\"\n```\n\nThis component will recursively mount all files from the current directory and\nwill serve them at the configured route. If an `index.html` file is in the source root,\nit will be served if no file is specified.\n\nRunning the static server:\n\n```shell\n$ spin up --listen 127.0.0.1:3000 --file spin.toml\n```\n\nAt this point, the component is going to serve all files in the current\ndirectory, and this can be tested using `curl`:\n\n```shell\n$ curl localhost:3000/LICENSE\n                              Apache License\n                        Version 2.0, January 2004\n                    http://www.apache.org/licenses/\n\nTERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n...\n```\n\nSee also the [rust-standalone example](./examples/rust-standalone/) showing use of the file server\nalongside a simple Rust-based application.\n\n### Component composition with the file server\n\nThe file server can also be composed with application logic to form one binary that can be run\nas a Spin application. See the following examples using the language and toolchains of your choice:\n\n- [Rust](./examples/rust)\n- [Javascript](./examples/javascript)\n- [Python](./examples/python)\n\n## Configuration options\n\nThe Spin fileserver supports various configuration options.\n\n### Setting the cache header\n\nCurrently, this file server has a single cache header that it can set through\nthe `CACHE_CONTROL` environment variable. If no value is set, the default\n`max-age=60` is used instead for all media types.\n\n### Setting the fallback path\n\nYou can configure a `FALLBACK_PATH` environment variable that points to a file that\nwill be returned instead of the default 404 Not Found response. If no environment\nvalue is set, the default behavior is to return a 404 Not Found response. This behavior\nis useful for Single Page Applications that use view routers on the front-end like React and Vue.\n\n```toml\n# For more on configuring a component, see: https://developer.fermyon.com/spin/writing-apps#adding-environment-variables-to-components\n[component.fs]\nsource = \"target/wasm32-wasip1/release/spin_static_fs.wasm\"\nfiles = [{ source = \"test\", destination = \"/\" }]\nenvironment = { FALLBACK_PATH = \"index.html\" }\n```\n\n### Using a custom 404 document\n\nYou can configure a `CUSTOM_404_PATH` environment variable and point to a file that will be served instead of returning a plain 404 Not Found response. Consider the following sample where the `spin-fileserver` component is configured to serve all files from the `test` folder. The desired page must exist in the `test` folder to send a custom 404 HTML page (here, `404.html`) instead of a plain 404 Not Found response.\n\n```toml\n# For more on configuring a component, see: https://developer.fermyon.com/spin/writing-apps#adding-environment-variables-to-components\n[component.fs]\nsource = \"target/wasm32-wasip1/release/spin_static_fs.wasm\"\nfiles = [{ source = \"test\", destination = \"/\" }]\nenvironment = { CUSTOM_404_PATH = \"404.html\" }\n```\n\n### Fallback favicon\n\nIf you haven't specified a favicon in your HTML document, `spin-fileserver` will serve the [Spin logo](./spin-favicon.png) as the fallback favicon. The `spin-fileserver` also serves the fallback favicon if the file (called `favicon.ico` or `favicon.png`) specified in your `\u003clink rel=\"shortcut icon\" ...\u003e` element does not exist.\n\nRemember that there are situations where `spin-fileserver` cannot serve the fallback favicon if no `\u003clink rel=\"shortcut icon\" ...\u003e` element is specified. Browsers try to find the favicon in the root directory of the origin (`somedomain.com/favicon.ico`). If the application doesn't listen for requests targeting that route, it can't intercept requests to non-existing favicons.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspinframework%2Fspin-fileserver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspinframework%2Fspin-fileserver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspinframework%2Fspin-fileserver/lists"}