This guide will walk you through adding scripts to package.json that will build the three parts of a Phoria solution that are required when running in production:
- Phoria Islands
- Phoria Web App
- Phoria Server
Also included in this guide are instructions for adding preview scripts so that you can run the production build in the local environment for testing purposes.
Tip
If you cloned an example project to get started you should already have build and preview scripts included in your package.json. This guide is for those who want to add these scripts manually to their solution, or for those who want to understand more about what the scripts do.
These are the scripts that you will need to add to build your Phoria solution for production:
{
"scripts": {
"build": "run-p build:* -c",
"build:islands": "vite build --app",
"build:webapp": "dotnet build --configuration Release",
"build:server": "vite build --config vite.server.config.ts"
}
}The next sections of the guide will describe each script in turn and any dependencies that you will need to add to your project to support them.
When you have added the scripts and all required dependencies you can build your Phoria solution for production by running:
pnpm run buildThis script is a convenience script that uses the npm-run-all package to run the other three build scripts in parallel.
pnpm add -D npm-run-allNote
npm-run-all is not required and you can use some other package or tool or shell feature (e.g. &) to do the same thing, if you prefer. The reason it is used here is because & doesn't work consistently on Windows and we want our scripts to be platform-agnostic.
This script uses Vite's Environment API to build the optimised CSR and SSR bundles that will be used in production and it also produces a manifest for Phoria to use:
- The CSR bundles are used by Phoria Islands to load component assets on the client
- The SSR bundles are used by the Phoria Server to load component assets on the server
- The manifest is used by the Phoria Web App to generate preload directives
The build configuration for Vite is provided via your Vite config file (e.g. vite.config.ts), and the configuration for Phoria specifically is provided via the phoria* Vite plugins.
By default, the build output will be placed in the <Vite root>/dist directory.
This script uses the dotnet CLI to build the Phoria Web App in its Release configuration.
By default, the build output will be placed in the <WebApp root>/bin/Release/<Target framework> directory.
Warning
You may need to adjust this command depending on the structure of your project to point to a specific solution (.sln) or project (.csproj) file.
This script uses Vite to build the Phoria Server. It uses a different Vite config file (vite.server.config.ts) because it does not share its configuration with Phoria Islands and needs specific configuration options.
Below is an example of a vite.server.config.ts that you can use:
import { join } from "node:path"
import { parsePhoriaAppSettings } from "@phoria/phoria/server"
import { type UserConfig, defineConfig } from "vite"
export default defineConfig(async () => {
const dotnetEnv = process.env.DOTNET_ENVIRONMENT ?? process.env.ASPNETCORE_ENVIRONMENT ?? "Development"
const appsettings = await parsePhoriaAppSettings({
environment: dotnetEnv,
cwd: join(process.cwd(), "WebApp")
})
return {
root: appsettings.root,
base: appsettings.base,
build: {
ssr: true,
target: "es2022",
copyPublicDir: false,
emptyOutDir: true,
outDir: `${appsettings.build.outDir}/server`,
rollupOptions: {
input: `${appsettings.root}/src/server.ts`
}
}
} satisfies UserConfig
})If you use the configuration above, the build output will be placed in the <Vite root>/dist/server directory.
Tip
The parsePhoriaAppSettings function is provided by the @phoria/phoria package and is used to read the appsettings file(s) in the WebApp project and provide the configuration to Vite. This is useful for sharing configuration between the Phoria Server and the Phoria Web App.
Note
You don't need to use Vite to build the Phoria Server. You could use something like tsup or any other TypeScript to JavaScript transpiler or bundler if you prefer. It is just convenient to use Vite because we are already using it to build our Phoria Islands and means that we don't need to add another dependency.
You could also decide to just use JavaScript for your Phoria Server and avoid a build step entirely if that's what you want to do.
These are the scripts that you will need to preview the production build of our Phoria solution locally:
{
"scripts": {
"preview": "run-p preview:* -c",
"preview:webapp": "cross-env DOTNET_ENVIRONMENT=Preview dotnet run --project ./WebApp/WebApp.csproj -c Release --launch-profile Preview",
"preview:server": "cross-env NODE_ENV=production DOTNET_ENVIRONMENT=Preview node ./WebApp/ui/dist/server/server.js"
}
}The next sections of the guide will describe each script in turn and any dependencies that you will need to add to your project to support them.
When you have added the scripts and all required dependencies you can preview your production build by running:
# Build the Phoria solution
pnpm run build
# Preview the Phoria solution
pnpm run previewThis script is a convenience script that uses the npm-run-all package to run the other three preview scripts in parallel.
Note
This guide will assume that you are using npm-run-all in your build script so there is no need to install it again, but if you did choose to use something else for your build script you will need to make the same adjustments here.
This script uses the dotnet CLI to run the Phoria Web App produced by the build:webapp script.
The cross-env package is used to set the DOTNET_ENVIRONMENT environment variable so you can use specific configuration or conditional branching in your code etc that targets the Preview environment if you wish.
pnpm add -D cross-envNote
cross-env is used because we want our scripts to be platform-agnostic, but is not required if you do not need to support Windows environments.
This script also uses a launch profile named Preview, which you can add to your launchSettings.json file:
{
"profiles": {
"Preview": {
"commandName": "Project",
"dotnetRunMessages": true,
"launchBrowser": true,
"applicationUrl": "http://localhost:5245",
"environmentVariables": {
"DOTNET_ENVIRONMENT": "Preview"
}
}
}
}Warning
You may need to adjust this command depending on the structure of your project to point to the actual location of your Phoria Web App's .csproj file.
This script uses node to run the Phoria Server produced by the build:server script. cross-env is used again to set environment variables used by the script.
Warning
You may need to adjust this command depending on your configuration to point to the location of the Phoria Server output produced by the build:server script.
If you would now like to try deploying your production build you can check out the deployment guide.