Building a Sitevision WebApp from Scratch

This recipe guides you through creating and deploying a minimal Sitevision WebApp module using React.

By following the steps in this guide, you will build a simple module that renders a greeting message and displays it on a page in Sitevision. The recipe covers the complete workflow—from creating the project to publishing the module on a public page.

The goal of this recipe is not to build a complex application, but to help you understand the core development flow for Sitevision WebApps.

Level: Beginner
Estimated time: 30–60 minutes
Outcome: A working WebApp installed and published on a Sitevision site.
Id: recipe-001-create-and-publish-module
Version: 1.0

Prerequisites:

Access to a Sitevision environment.
Basic Javascript knowledge.
Development environment configured.
Permission to add and install modules on web site.

Step 1 — Create the project

Intent

Create a new Sitevision WebApp (React) project with the default project structure and development configuration.

Input

An empty directory where the project will be created.

Output

A new project folder: hello-world-webapp
A generated project structure including required files (`manifest.json`, `src/index.js`, `src/main.js`)

Commands

Run the following command in your terminal:

Create Sitevision App script

npx @sitevision/create-sitevision-app hello-world-webapp

CLI configuration

During project creation you will be prompted with a few questions. Use the following values:

Question	Answer
What type of app do you want to create?	WebApp (React)
Do you want to use TypeScript?	No
Server-side rendering only?	No
Development domain	Your development domain (or localhost)
Development site name	Site name
Development addon name	Hello World App
Username for development site	Username
Password for development site	*********
Use (unsafe) HTTP for local development	Yes, if running Sitevision locally, otherwise, No

Verification

Run in terminal:

Verify that files have been created

cd hello-world-webapp

ls

The following files must exist for a valid WebApp project:

Following files must exist:

text

manifest.json  
src/index.js  
src/main.js

Acceptance check

The step is successful when:

The project folder opens correctly in your IDE
manifest.json, src/index.js, and src/main.js exist
.dev_properties.json exists (used later for deployment with `npm run dev`)

Common issues

npx command not found

Make sure Node.js and npm are installed.

Incorrect development settings

If needed, you can update the file .dev_properties.json after the project has been created.

Step 2 — Implement minimal rendering (Hello World)

Intent

Implement a minimal WebApp that server-side renders a React component and then hydrates it on the client so the module displays content on the page in Sitevision.

Input

A WebApp project created in Step 1.
The following files already exist:

Validate boilerplate files

text

manifest.json  
src/index.js  
src/main.js  
src/components/App.js

Output

A WebApp that renders:

WebApp output

text

Hello world! < name >

The value name is retrieved from appData (it may be empty if not configured).

Architecture overview

The WebApp follows a simple SSR → Hydration architecture.

Architecture overview

text

Request  
   ↓  
src/index.js (Server-side rendering)  
   ↓  
HTML + initialState  
   ↓  
src/main.js (Client hydration)  
   ↓  
React App (App.js)

Rendering flow

Server-side rendering (index.js)

When a user loads the WebApp, a route handler renders the React component on the server using renderToString.

The server sends the HTML along with an initialState.

Client-side hydration (main.js)

When the page loads, React attaches event handling and state to the existing HTML using hydrateRoot.

UI component (App.js)

A React component displays the greeting message and the optional name.

2.1 Verify WebApp manifest

Goal

Ensure the WebApp metadata and dependencies are correctly defined.

Open manifest.json and verify that it contains at least the following fields:

manifest.json file

json

{  
  "id": "hello-world-webapp",  
  "version": "0.0.1", 
  "name": {
    "en": "Hello World WebApp Cookbook recipe 001",
    "sv": "Hello World WebApp Kokbok recept 001"
  },
  "author": "Author",
  "description": {
	"en": "Hello World WebApp Cookbook recipe",
	"sv": "Hello World WebApp Kokbok recept"
  }, 
  "helpUrl": "https://developer.sitevision.se/cookbook", 
  "type": "WebApp",  
  "bundled": true,  
  "requiredLibs": {  
    "react": "18.3.1"  
  }  
}

Verification

type is "WebApp"
id and version exist

2.2 Implement server-side rendering

Goal

Render the React component on the server and return the HTML with the initial state.

Replace the contents of:

index.js file

text

src/index.js

With:

Updated index.js file

import * as React from 'react';
import { renderToString } from "react-dom/server";  
import router from "@sitevision/api/common/router";  
import appData from "@sitevision/api/server/appData";  
import App from "./components/App";  
  
router.get("/", (req, res) => {  
  const message = "Hello, world!";  
  const name = appData.get("name") || "";  
  
  res.agnosticRender(renderToString(<App message={message} name={name} />), {  
    message,  
    name  
  });  
});

Verification

router.get("/") exists
res.agnosticRender() is used to send the HTML response

2.3 Implement client hydration

Goal

Attach React interactivity to the server-rendered HTML.

Replace the contents of:

main.js file

text

src/main.js

With:

Updated main.js file

import * as React from 'react';
import { hydrateRoot } from "react-dom/client";  
import App from "./components/App";  
  
export default (initialState, el) => {  
  hydrateRoot(  
    el,  
    <App message={initialState.message} name={initialState.name} />  
  );  
};

Verification

hydrateRoot(el, ...) is used.
initialState.message and initialState.name are passed to the component

2.4 Implement the UI component

Goal

Create a simple React component that displays the greeting message.

Replace the contents of:

App.js file

text

src/components/App.js

With:

Updated App.js file

import * as React from 'react';
import PropTypes from "prop-types";  
import styles from "./App.scss";  
  
const App = ({ message, name }) => {  
  return (  
    <div className={styles.container}>  
      <p className={styles.text}>  
        {message} {name}  
      </p>  
    </div>  
  );  
};  
  
App.propTypes = {  
  message: PropTypes.string,  
  name: PropTypes.string  
};  
  
export default App;

Verification

The component renders {message} {name}
App is exported as default

Acceptance check

Step 2 is complete when:

manifest.json contains valid WebApp metadata
src/index.js renders the component using agnosticRender
src/main.js hydrates the React app using hydrateRoot
src/components/App.js renders the greeting message

Step 3 — Build and package the WebApp

Intent

Build the WebApp and generate a deployable artifact that can be uploaded and installed in Sitevision.

Input

A WebApp project with implemented rendering logic (from Step 2)
Source code located in:

src/

text

src/

Output

A compiled WebApp artifact:

hello-world-webapp.zip path

text

dist/hello-world-webapp.zip

This `.zip` file is the deployable WebApp package that will be installed in Sitevision.

Build process overview

During the build process:

Build process overview

text

src/ (source code)  
      ↓  
npm run build  
      ↓  
dist/ (compiled bundle + WebApp package)

The build script:

bundles JavaScript and CSS
prepares the WebApp for deployment
creates a `.zip` artifact

3.1 Run the build script

From the project root, run:

Sitevision build script

npm run build

The build script compiles the source code and packages the WebApp.

3.2 Verify build output

After the build finishes, verify that a dist directory exists in the project root.

Run:

Validate existence of dist folder and built artifact

ls dist

Expected output:

hello-world-webapp.zip

The file: hello-world-webapp.zip is the WebApp artifact created by the build process.

Verification

Confirm the following:

The build command runs without errors.
A dist/ folder exists.
The file hello-world-webapp.zip is created.

Acceptance check

Step 3 is successful when:

The build process completes successfully
The dist/ directory exists
A deployable WebApp artifact (.zip) is generated

Step 4 — Install the WebApp in Sitevision

Intent

Deploy and install the WebApp in your Sitevision environment so it becomes available as a module that can be placed on a page.

Input

A built WebApp artifact from Step 3
A configured development environment
The configuration file:

.dev_properties.json

Output

An Addon container created in Sitevision
A deployed WebApp version uploaded to the Sitevision repository
The module available in the Module selector

Concept: Addons and WebApps

In Sitevision, a WebApp must belong to an Addon.

Addon container

text

Addon  
 ├── WebApp version 0.0.1  
 ├── WebApp version 0.0.2  
 └── WebApp version 0.1.0 (Active)

The Addon acts as a container that can store multiple versions of the same WebApp.

Prerequisites

Before deploying, verify the following:

1. Development configuration exists

The file below must exist and contain valid credentials:

.dev_properties.json

Example configuration:

.dev_properties.json

json

{  
  "domain": "dse-test.sitevision.se",  
  "siteName": "Website name",  
  "addonName": "Hello World addon",  
  "username": "user",  
  "password": "*********",  
  "useHTTPForDevDeploy": false  
}

2. REST API access is enabled

The Sitevision site must allow REST requests.

Enable this in:

Site Settings → REST API

4.1 Create the Addon container

Create the Addon in Sitevision using the deployment script.

Run:

Create Addon script

npm run create-addon

Expected response:

Expected create-addon script response

json

Addon creation successful:  
{  
  "id": "180.5a7c388919cacfec9cc15d",  
  "type": "sv:customModule",  
  "name": "Hello World addon",  
  "path": "/Website/Addon Repository/Hello World addon"  
}

This creates the Addon container that will store WebApp versions.

4.2 Deploy the WebApp

Once the Addon exists, deploy the WebApp to the environment.

Run:

Run Sitevision dev script

npm run dev

The script will:

Upload the WebApp to Sitevision.
Deploy a new version.
Watch the project files.
Automatically redeploy when files change and overwrite the current version.

Expected response:

Expected response from npm run dev

json

Upload successful:  
{  
  "id": "360.5a7c388919cacfec9cc160",  
  "type": "sv:webApp",  
  "name": "hello-world-webapp-0.0.1",  
  "path": "/Website/WebApp Repository/hello-world-webapp-0.0.1"  
}

Verification

Verify that the WebApp exists in Sitevision.

Open the Sitevision edit interface and navigate to:

Addons view

Confirm that:

The Addon exists.
The WebApp version is uploaded.

Acceptance check

Step 4 is successful when:

The Addon container exists in Sitevision.
A WebApp version is uploaded.
No errors appear in the deployment output.

Common issues

Authentication failure

Check credentials in: .dev_properties.json

REST API calls blocked

Enable REST requests in: Site Settings → REST API

Step 5 — Place the module on a page

Intent

Add the deployed WebApp module to a page in the Sitevision editor so it can render content.

Input

A deployed WebApp from Step 4.
Access to the Sitevision editor
A page where the module can be placed

Output

The WebApp module added to a content area on a page.
The module renders content in edit mode / preview

5.1 Open the Sitevision editor

Example navigation:

Website → Edit → Select page → Add module

5.2 Open the Module selector

In the editor toolbar, open the Module selector.

You can find modules in two ways:

Search for the module by name
Browse modules by category

Search for the module you deployed earlier, for example: "Hello World WebApp"

5.3 Add the module to the page

When the module is added:

The WebApp configuration panel will appear.
Default configuration values are loaded.

These configuration settings were generated by the create-sitevision-app boilerplate.

Configuration customization will be covered in a later recipe.

Verification

Confirm the following:

The module appears in the content area.

The module renders content in the editor.

The text `Hello, world!` (and optional name) is visible in preview

Acceptance check

Step 5 is successful when:

The module can be added to the page.
The module renders content in edit mode / preview.

Step 6 — Publish the page

Intent

Publish the page so the WebApp module becomes visible on the public website.

Input

A page containing the WebApp module (from Step 5).

Output

The page is published.
The module renders on the public URL.

6.1 Publish the page

In the Sitevision editor, click: Publish

6.2 Open the public page

Open the public URL of the page in your browser.

Example: https://example.sitevision.se/page

Verification

Confirm that:

The page loads successfully
The module renders the greeting message

Expected output example:

Hello, world!

Hello, world! John Doe