Adapter for Svelte apps that creates an Azure Static Web App, using an Azure function for dynamic server rendering. If your app is purely static, you may be able to use adapter-static instead.
See the demo folder for an example integration with the SvelteKit demo app. The demo is automatically deployed to Azure SWA on every commit to the main branch.
Run npm install -D svelte-adapter-azure-swa
.
Then in your svelte.config.js
:
import azure from 'svelte-adapter-azure-swa';
export default {
kit: {
...
adapter: azure()
}
};
And, if you use TypeScript, add this to the top of your src/app.d.ts
:
/// <reference types="svelte-adapter-azure-swa" />
When deploying to Azure, you will need to properly configure your build so that both the static files and API are deployed.
property | value |
---|---|
app_location |
./ |
api_location |
build/server |
output_location |
build/static |
If you use a custom API directory (see below), your api_location
will be the same as the value you pass to apiDir
.
If your app_location
is in a subfolder (e.g. ./my_app_location
), then your api_location
should include the path to that subfolder (e.g. my_app_location/build/server
.) output_location
should still be build/static
.
Oryx, Azure's build system, may attempt to build your application with an EOL version of Node that SvelteKit doesn't support. If you get an error like "Unsupported engine - Not compatible with your version of node/npm", you can force Oryx to use the correct version by setting an engines
field in your app's package.json
:
"engines": {
"node": ">=18.13 <19"
}
You can debug using the Azure Static Web Apps CLI. Note that the CLI is currently in preview and you may encounter issues.
To run the CLI, install @azure/static-web-apps-cli
and the Azure Functions Core Tools and add a swa-cli.config.json
to your project (see sample below). Run npm run build
to build your project and swa start
to start the emulator. See the CLI docs for more information on usage.
{
"configurations": {
"app": {
"outputLocation": "./build/static",
"apiLocation": "./build/server",
"host": "127.0.0.1"
}
}
}
The directory where the sk_render
Azure function for SSR will be placed. Most of the time, you shouldn't need to set this.
By default, the adapter will output the sk_render
Azure function for SSR in the build/server
folder. If you want to output it to a different directory instead (e.g. if you have additional Azure functions to deploy), you can set this option.
import azure from 'svelte-adapter-azure-swa';
export default {
kit: {
...
adapter: azure({
apiDir: 'custom/api'
})
}
};
If you set this option, you will also need to create a host.json
and package.json
in your API directory. The adapter normally generates these files by default, but skips them when a custom API directory is provided to prevent overwriting any existing files. You can see the default files the adapter generates in this directory.
For instance, by default the adapter outputs these files...
build/
└── server/
├── sk_render/
│ ├── function.json
│ └── index.js
├── host.json
├── local.settings.json
└── package.json
... but only outputs these files when a custom API directory is provided:
custom/
└── api/
└── sk_render/
├── function.json
└── index.js
Also note that the adapter reserves the folder prefix sk_render
and API route prefix __render
for Azure functions generated by the adapter. So, if you use a custom API directory, you cannot have any other folder starting with sk_render
or functions available at the __render
route, since these will conflict with the adapter's Azure functions.
The directory where the static assets will be placed. Most of the time, you shouldn't need to set this.
By default, the adapter will output the static JS, CSS and HTML files to the build/static
folder. If you want to output it to a different directory instead you can set this option.
import azure from 'svelte-adapter-azure-swa';
export default {
kit: {
...
adapter: azure({
staticDir: 'custom/static'
})
}
};
An object containing additional Azure SWA configuration options. This will be merged with the staticwebapp.config.json
generated by the adapter.
Attempting to override the default catch-all route (route: '*'
) or the navigationFallback
options will throw an error, since they are critical for server-side rendering.
Note: customizing this config (especially routes
) has the potential to break how SvelteKit handles the request. Make sure to test any modifications thoroughly.
import azure from 'svelte-adapter-azure-swa';
export default {
kit: {
...
adapter: azure({
customStaticWebAppConfig: {
routes: [
{
route: '/login',
allowedRoles: ['admin']
}
],
globalHeaders: {
'X-Content-Type-Options': 'nosniff',
'X-Frame-Options': 'DENY',
'Content-Security-Policy': "default-src https: 'unsafe-eval' 'unsafe-inline'; object-src 'none'",
},
mimeTypes: {
'.json': 'text/json'
},
responseOverrides: {
'401': {
'redirect': '/login',
'statusCode': 302
}
},
platform: {
apiRuntime: 'node:20'
}
}
})
}
};
In production, Azure SWA will route any requests to /api
or /api/*
to the SWA API backend. If you also define SvelteKit routes beginning with /api
, those requests will work in dev, but return a 404 in production since the request will be routed to the SWA API. Because of this, the adapter will throw an error at build time if it detects any routes beginning with /api
.
If you want to disable this check, you can set allowReservedSwaRoutes
to true. However, this will not start routing /api
requests to your SvelteKit app. SWA does not allow configuring the /api
route.
import azure from 'svelte-adapter-azure-swa';
export default {
kit: {
...
adapter: azure({
allowReservedSwaRoutes: true
})
}
};
An object containing additional esbuild options. Currently only supports external, keepNames, and loader. If you require additional options to be exposed, please open an issue.
import azure from 'svelte-adapter-azure-swa';
export default {
kit: {
...
adapter: azure({
esbuildOptions: {
external: ['fsevents'],
keepNames: true
}
})
}
};
SWA provides some information to the backend functions that this adapter makes available as platform-specific context. This is available in hooks and server routes through the platform
property on the RequestEvent
.
To get typings for the platform
property, reference this adapter in your src/app.d.ts
as described in the usage section.
This contains the client principal as parsed from the x-ms-client-principal
request header. See the official SWA documentation or the types for further details.
This is currently only available when running in production on SWA. In addition, it is only available in certain circumstances in production - see this adapter issue for more details. Please report any issues you encounter.
All server requests to your SvelteKit app are handled by an Azure function. This property contains that Azure function's request context.
If you're deploying your app from a monorepo, here's what you need to know.
The build currently fails if you use pnpm
as a package manager. You can track this issue for updates. For now, you can work around the issue by using npm
instead.
Also, since your SvelteKit app is in a subfolder of the monorepo, you will need to update your deployment workflow.
For instance, if you have the following folder structure:
apps/
├── sveltekit-app
└── other-app
The app_location
and api_location
in your deployment configuration need to point to the apps/sveltekit-app
subfolder. output_location
should remain the same. Here's how that would look for an Azure SWA GitHub workflow:
steps:
- uses: actions/checkout@v2
with:
submodules: true
- name: Build And Deploy
id: builddeploy
uses: Azure/static-web-apps-deploy@v1
with:
azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_ORANGE_GRASS_0778C6300 }}
repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for Github integrations (i.e. PR comments)
action: "upload"
###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
# For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
- app_location: "./" # App source code path
- api_location: "build/server" # Api source code path - optional
+ app_location: "./apps/sveltekit-app" # App source code path
+ api_location: "apps/sveltekit-app/build/server" # Api source code path - optional
output_location: "build/static" # Built app content directory - optional
###### End of Repository/Build Configurations ######