sveltekit-adapter-iis
v1.4.1
Published
A SvelteKit Adapter for IIS Web Servers
Downloads
504
Readme
SvelteKit Adapter IIS
This package contains an adapter for Sveltekit that will make your project output deployable to IIS.
Usage
- Install to your sveltekit project
From npm
pnpm add -D sveltekit-adapter-iis
#or
npm i sveltekit-adapter-iis --save-dev
#or
yarn add sveltekit-adapter-iis --dev
- In your
svelte.config.js
file replace default adapter withIISAdapter
import { vitePreprocess } from '@sveltejs/kit/vite'
import IISAdapter from 'sveltekit-adapter-iis'
/** @type {import('@sveltejs/kit').Config} */
const config = {
preprocess: vitePreprocess(),
kit: {
version: {
pollInterval: 300000,
},
adapter: IISAdapter({
// the hostname/port that the site will be hosted on in IIS.
// can be changed later in web.config
origin: 'http://localhost:80XX',
// ... other options
}),
},
}
export default config
- Build the project
pnpm build
#or
npm run build
- Install dependencies
You should try to bundle all your dependencies as dev dependencies so that you can skip this step however not all dependencies play nice. In this case you can install just the production dependencies using your preferred package manager.
npm
npm install --omit-dev
pnpm
pnpm install --P
yarn
yarn install --production=true
bun
bun install --production
Deploy the files to IIS
Prerequisites
- IIS 7.0 or greater with
IISRewrite
module and iisnode installed - Check out Setting up IIS or IIS Troubleshooting if needed.
Option 1: Direct point to output directory
- This is useful for local testing with IIS running on your machine
- You will have to stop the website and possibly IIS every time when re-building.
1 . In IIS Manager add a new Website: Sites -> Add Website...
2. Set the Physical Path
to <your project>/.svelte-kit/adapter-iis
.
Option 2: Copying build output elsewhere
- create a new folder in
C:/inetpub/<your project>
- copy the contents of
<your project>/.svelte-kit/adapter-iis
intoC:/inetpub/<your project>
- In IIS Manager add a new Website:
Sites -> Add Website...
- Set the
Physical Path
toC:/inetpub/<your project>
.
Setting up IIS
This is not a complete guide, but it should help.
- Enable IIS on your local machine for testing
- Restart your computer, check if it works by going to
localhost
without a port - Find the IIS manager program (recommended: pin it to start)
C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Administrative Tools
Internet Information Services (IIS) Manager
- or:
%windir%\system32\inetsrv\InetMgr.exe
- Install URL Rewrite and iisnode modules
- URLRewrite:
English x64
- iisnode:
iisnode-full-vx.x.x-x64.msi
- URLRewrite:
- Restart IIS from the manager:
- Unlock the section in global config (More information needed)
- Set some permission to
Read/Write
instead ofRead Only
(More information needed) - Set up logs:
- Set
iisNodeOptions.loggingEnabled
totrue
in the adapter options - (Optional) Configure a path for the logs using
iisNodeOptions.logDirectory
- Set
IIS troubleshooting
- Locked section error
- URLs are not being handled by sveltekit
- UrlRewrite rule might not be enabled
- Node executable cannot be found
- By default the nodeExePath is set to
node.exe
to override this setiisNodeOptions.overrideNodeExePath
.
const config = { //... kit: { adapter: IISAdapter({ iisNodeOptions: { nodeProcessCommandLine: 'C:\\Program Files\\nodejs\\node.exe', // or whatever the path is }, }), }, }
- By default the nodeExePath is set to
- Logs not being written, builds fail if server is running with
EBUSY
fs error.- Set up file permissions for log dir & for
adapter-iis
dir for IIS_USER or Everyone to allow all - If they are still not being written, instead of
console.log
, try usingconsole.warn
- it will show up instderr
logs without stopping the server. - IIS likes to often overwrite log files instead of creating new ones, so make sure you open+close your text editor to see the latest log contents.
- Set up file permissions for log dir & for
- Images or scripts outside of sveltekit (e.g. Virtual Directories, or external) fail to load
- If you are using a full url with
https://
protocol, and have not set up SSL certificates in IIS, it will fail due to 'Cannot provide secure connection'- If the url's on the same origin, try using a relative URL
- example:
/virtual-images/image1.png
instead ofhttps://localhost:XXXX/virtual-images/image1.png
- example:
- If the url's on a different origin, try changing it to
http
instead ofhttps
- If you're generating the url, on the URL object, you can change the
protocol
key - make sure to build it with
https
once deploying to production
- If you're generating the url, on the URL object, you can change the
- If the url's on the same origin, try using a relative URL
- You could also probably set the site to use https in IIS, in site settings.
- If you are using a full url with
- POST requests or form actions fail with error 403
- Either you forgot to specify the
origin
option, or it is mismatched - Set it like this:
This sets it in// svelte.config.js const config = { //... kit: { adapter: IISAdapter({ origin: 'http://localhost:8010', // or whatever the site's origin is when you deploy it using IIS }), }, }
web.config
during building. - Either you forgot to specify the
- Only seeing default Error Page when accessing the app remotely
- You need to enable
Detailed errors
in IIS for the site. - Navigate to the site in IIS Manager
- Open
Error Pages
- Click
Edit Feature Settings...
under the Actions menu on the right - Change Error Responses to
Detailed Errors
. This will allow Sveltekit to handle errors itself.
- You need to enable
outputWhitelist
This adapter also provides outputWhitelist
in options. This is useful when you need some extra directories on server for the app to function. You can do the following:
Use rollup-plugin-copy
to copy the files
// vite.config.ts
import { resolve } from 'node:path'
import { defineConfig, normalizePath } from 'vite'
import copy from 'rollup-plugin-copy'
// your define config does not need to be a function, i think
// i did it like this to make sure thecopy plugin only runs when building
export default defineConfig(({ command }) => {
const config = {
// ...
plugins: [],
}
if (command === 'build') {
const copyPlugin = copy({
targets: [
{
// some files you want to copy over
src: [
'db/*.htaccess',
'db/schema.json',
'db/*SCINDEX.json',
'db/vtmeta.yml',
],
dest: normalizePath(resolve('.svelte-kit', 'adapter-iis', 'db')),
},
],
hook: 'writeBundle',
})
config.plugins.push(copyPlugin)
}
return config
})
set the outputWhitelist
// svelte.config.js
const config = {
//...
kit: {
adapter: IISAdapter({
// origin, ...
outputWhitelist: ['db'],
}),
},
}
Now, when building, .svelte-kit/adapter-iis/db
should get preserved instead of being deleted
Using Virtual Directories
You might want to use the IIS feature 'Virtual Directory', where it maps a real directory onto a route.
To make sure sveltekit doesn't block this with a 404, modify externalRoutes
option in the adapter config:
// svelte.config.js
const config = {
//...
kit: {
adapter: IISAdapter({
// origin, ...
externalRoutes: ['cdn', 'images', 'viewer'],
}),
},
}
Then add some virtual directories that map to cdn
, images
, and viewer
.
Re-build the app, and these routes will be taken into account in the generated web.config
file.
/healthcheck
route
By default, since IIS can be quite tricky to set up, the adapter adds a simple /healthcheck
route, which responds with 'ok'
This is useful if you want to determine that the node server is running, but your main site isn't loading for whatever reson.
The route can be turned off setting the healthcheckRoute
adapter option to false
. (A re-build is needed to take effect.)
Handling stage specific environment variables
When providing environment variables through a .env
file, the adapter will also look for any .env.{stage}
files in order to create web.{stage}.config
transformation files in .svelte-kit/adapter-iis
. These transformation files can later be used to perform XML Transformation steps in your CI/CD pipelines based on which stage is being deployed to.
Read more about XML Transformations here: XML Transformation in Azure Pipelines
Redirecting requests to HTTPS
// svelte.config.js
const config = {
//...
kit: {
adapter: IISAdapter({
// origin, ...
redirectToHttps: true,
}),
},
}
By setting the option redirectToHttps
to true
, a URL Rewrite rule is applied to the web.config
file that redirect all non-HTTPS request to HTTPS.
httpErrors
By default IIS will take control of HTTP errors and show the default IIS [STATUS].htm
for each status. If you want the SvelteKit application to handle all HTTP errors, you can specify httpErrors.existingResponse
with PassThrough
to let the application handle the errors.
// svelte.config.js
const config = {
//...
kit: {
adapter: IISAdapter({
// origin, ...
httpErrors: {
existingResponse: 'PassThrough',
},
}),
},
}
Disclaimer
Note that this only works when served from the root of a domain.
So you can serve it from www.mysvelteapp.com
or sub.mysvelteapp.com
but it will not work from www.mysvelteapp.com/subfolder
. Unfortunately this is due to how routing works with sveltekit. Adding the base
property to your sveltekit config causes all of the routes to have that appended so you end up with the app living on www.mysevelteapp.com/subfolder/subfolder
.
How it works
This adapter wraps adapter-node
from @sveltejs/kit
and uses node:http
as the web server. It outputs a web.config file that rewrites incoming requests to the node:http
server.
Contributions
Contributions are welcome! Please open an issue or submit a PR if you would like to help out with this project!