Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/gornostay25/svelte-adapter-bun

A SvelteKit adapter for Bun
https://github.com/gornostay25/svelte-adapter-bun

bun bunjs svelte sveltekit sveltekit-adapter

Last synced: 3 days ago
JSON representation

A SvelteKit adapter for Bun

Awesome Lists containing this project

README 

        
# svelte-adapter-bun



[Adapter](https://kit.svelte.dev/docs/adapters) for SvelteKit apps that generates a standalone [Bun](https://github.com/oven-sh/bun) server.



## :zap: Usage



Install with `bun add -d svelte-adapter-bun`, then add the adapter to your `svelte.config.js`:



```js

// svelte.config.js

import adapter from "svelte-adapter-bun";



export default {

  kit: {

    adapter: adapter(),

  },

};

```



After building the server (`vite build`), use the following command to start:



```

# go to build directory

cd build/



# run Bun

bun run start

```



## :gear: Options



The adapter can be configured with various options:



```js

// svelte.config.js

import adapter from "svelte-adapter-bun";

export default {

  kit: {

    adapter: adapter({

      out: "build",

      assets: true,

      envPrefix: "MY_CUSTOM_",

      development: true,

      // precompress: true,

      precompress: {

        brotli: true,

        gzip: true,

        files: ["htm", "html"],

      },

      dynamic_origin: true,

      xff_depth: 1,

    }),

  },

};

```



### out



The directory to build the server to. It defaults to `build` β€” i.e. `bun run start` would start the server locally after it has been created.



### assets



Browse a static assets. Default: `true`



- [x] Support [HTTP range requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests)



### precompress



Enables precompressing using gzip and brotli for assets and prerendered pages. It defaults to `false`.



#### brotli



Enable brotli precompressing. It defaults to `false`.



#### gzip



Enable gzip precompressing. It defaults to `false`.



#### files



file extensions to compress.It defaults to `['html','js','json','css','svg','xml','wasm']`.



### envPrefix



If you need to change the name of the environment variables used to configure the deployment (for example, to deconflict with environment variables you don't control), you can specify a prefix:



```js

envPrefix: "MY_CUSTOM_";

```



```

MY_CUSTOM_HOST=127.0.0.1 \

MY_CUSTOM_PORT=4000 \

MY_CUSTOM_ORIGIN=https://my.site \

bun build/index.js

```



### development



This enables bun's error page. Default: `false`



### dynamic_origin



If enabled use `PROTOCOL_HEADER` `HOST_HEADER` like origin. Default: `false`



### xff_depth



The default value of XFF_DEPTH if environment is not set. Default: `1`



## :spider_web: WebSocket Server



https://bun.sh/docs/api/websockets



```js

// hooks.server.js



/** @type {import("svelte-adapter-bun").WebSocketHandler} */

export const handleWebsocket = {

  open(ws) {

    console.log("WebSocket opened");

    ws.send("Slava UkraΡ—ni");

  },

  /**

   * @param {Request} request

   * @param {Function} upgrade

   */

  upgrade(request, upgrade) {

    const url = new URL(request.url);

    if (url.pathname.startsWith("/ws")) {

      return upgrade(request);

    }

  },

};

```



## Polyfills



If you need to use polyfills in your app, you can add them to the [`src/polyfills.js`](src/polyfills.js) file:



```js

class Polifill {

  constructor() {

    ...

  }

}



const globals = {

  Polifill,

};

```



## :desktop_computer: Environment variables



> Bun automatically reads configuration from `.env.local`, `.env.development` and `.env`



### `PORT` and `HOST`



By default, the server will accept connections on `0.0.0.0` using port 3000. These can be customized with the `PORT` and `HOST` environment variables:



```

HOST=127.0.0.1 PORT=4000 bun build/index.js

```



### `ORIGIN`, `PROTOCOL_HEADER` and `HOST_HEADER`



HTTP doesn't give SvelteKit a reliable way to know the URL that is currently being requested. The simplest way to tell SvelteKit where the app is being served is to set the `ORIGIN` environment variable:



```

ORIGIN=https://my.site bun build/index.js

```



With this, a request for the `/stuff` pathname will correctly resolve to `https://my.site/stuff`. Alternatively, you can specify headers that tell SvelteKit about the request protocol and host, from which it can construct the origin URL:



```

PROTOCOL_HEADER=x-forwarded-proto HOST_HEADER=x-forwarded-host bun build/index.js

```



> [`x-forwarded-proto`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto) and [`x-forwarded-host`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host) are de facto standard headers that forward the original protocol and host if you're using a reverse proxy (think load balancers and CDNs). You should only set these variables if your server is behind a trusted reverse proxy; otherwise, it'd be possible for clients to spoof these headers.



### `ADDRESS_HEADER` and `XFF_DEPTH`



The [RequestEvent](https://kit.svelte.dev/docs/types#additional-types-requestevent) object passed to hooks and endpoints includes an `event.clientAddress` property representing the client's IP address. [Bun.js haven't got functionality](https://github.com/Jarred-Sumner/bun/issues/518) to get client's IP address, so SvelteKit will receive `127.0.0.1` or if your server is behind one or more proxies (such as a load balancer), you can get an IP address from headers, so we need to specify an `ADDRESS_HEADER` to read the address from:



```

ADDRESS_HEADER=True-Client-IP bun build/index.js

```



> Headers can easily be spoofed. As with `PROTOCOL_HEADER` and `HOST_HEADER`, you should [know what you're doing](https://adam-p.ca/blog/2022/03/x-forwarded-for/) before setting these.

> If the `ADDRESS_HEADER` is `X-Forwarded-For`, the header value will contain a comma-separated list of IP addresses. The `XFF_DEPTH` environment variable should specify how many trusted proxies sit in front of your server. E.g. if there are three trusted proxies, proxy 3 will forward the addresses of the original connection and the first two proxies:



```

, , 

```



Some guides will tell you to read the left-most address, but this leaves you [vulnerable to spoofing](https://adam-p.ca/blog/2022/03/x-forwarded-for/):



```

, , , 

```



Instead, we read from the _right_, accounting for the number of trusted proxies. In this case, we would use `XFF_DEPTH=3`.



> If you need to read the left-most address instead (and don't care about spoofing) β€” for example, to offer a geolocation service, where it's more important for the IP address to be _real_ than _trusted_, you can do so by inspecting the `x-forwarded-for` header within your app.



## License



[MIT](LICENSE) Β© [Volodymyr Palamar](https://github.com/gornostay25)