Have you ever been to the Restaurant of Mistaken Orders? It's a place where you're served delicious dishes that you didn't order, but you end up loving them anyway! Imagine we're in the kitchen of that restaurant, cooking up a new Vite project for Sitecore Content Hub. Let's get started with this culinary-tech journey.
Setting Up a Vite Project for Sitecore Content Hub
1. Create a Vite Project
First, open up Visual Studio Code. Next, you'll need to create a Vite project.
To do this, use the npm command create Vite as follows:
npm create vite@latest
During the setup process, name your project appropriately. In this example, we're naming it "Sitecore.CH.ExternalComponents.React".
2. Choose Your Framework and Language
During the setup process, you will be asked to choose a framework and a variant. Select React for your framework and TypeScript as your variant.
3. Install Dependencies
Once your project setup is complete, change your directory to the root directory of your new project and install the necessary packages using the npm install command.
npm install
4. Verify Your Installation
With everything set up, you should now see the default files that are automatically built, including index.html. You'll also have your tsconfig.json pre-configured. Run the command npm run dev to verify that your installation is working properly.
npm run dev
5. Configure SSL
To configure your project for SSL, you should use certificates! we can create them using a command prompt as follow:
cd "C:\Program Files\Git\usr\bin"
.\openssl.exe req -x509 -newkey rsa:4096 -keyout c:\certs\key.pem -out c:\certs\cert.pem -days 365 -nodes -subj "/CN=localhost"
host: 'localhost',
port: 5000,
https: {
key: fs.readFileSync('certs/key.pem'),
cert: fs.readFileSync('certs/cert.pem'),
},
copy the certs folder to your project folder, and add the certs folder to .gitignore
.gitignor (example)
# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
lerna-debug.log*
node_modules
dist
dist-ssr
*.local
# Editor directories and files
.vscode/*
!.vscode/extensions.json
.idea
.DS_Store
*.suo
*.ntvs*
*.njsproj
*.sln
*.sw?
# Project Specific files
.env
# Project-Specific Directories
certs
in order to use fs "filesystem" in the vite.config file you need to add the following at the top of the vite.config file.
Example vite.config
import { defineConfig, loadEnv } from 'vite'
import react from '@vitejs/plugin-react'
import fs from 'fs'
export default defineConfig(({ command, mode }) => {
const env = loadEnv(mode, process.cwd(), '')
const isDev = mode === 'development';
return {
server: isDev ? {
host: 'localhost',
port: 5000,
https: {
key: fs.readFileSync('certs/key.pem'),
cert: fs.readFileSync('certs/cert.pem'),
},
proxy: {
'^/api/.*': {
target: env.HOST_URL,
changeOrigin: true,
secure:false,
auth: `'${env.USERNAME}:${env.PASSWORD}'`,
rewrite: (path) => path.replace(/^\/api/, '')
},
},
}:{},
build: {
sourcemap: true,
minify: true,
target: 'es2015',
lib: {
formats: ['es'],
fileName: process.env.npm_config_component,
entry: `./src/components/${process.env.npm_config_component}/index.tsx`,
},
},
define: isDev ? {
//'process.env.API_URL': JSON.stringify(apiUrl)
}:{},
}
})
6. Update Your package.json
The next step is to configure your run script in your package.json file. Make sure to enable hosting and SSL, and also ensure that CORS is enabled. This is necessary to run your script inside Content Hub.
"scripts": {
"watch": "vite build --watch",
"dev": "vite --host -- https --cors",
"build": "tsc && vite build"
},
In some cases you need to add your localhost URL to the CORS settings in Content Hub, you can find this in manage > settings > CORSConfiguration
7. Clean Up Your Project
Before proceeding further, it's a good idea to clean up your project a bit. Delete any unnecessary assets and files, leaving only your Vite configurations and environment variables. You can also delete the public folder.
8. Create Your First Component
Now that your project is all setup, it's time to start building.
Prepping the Kitchen
Just like in a real kitchen, where you need to prepare your ingredients and tools before starting to cook, we'll have to complete some setup steps. Visit the 'Additional Steps' section for more details.
Step 1: Setting up the Component Structure
Think of this as laying out your ingredients. In our Sitecore Content Hub project, navigate to the "components" directory. Here, create a new folder named "example-component", just like how you'd prepare and lay out your ingredients before cooking.
Step 2: Create the Component File
This is akin to prepping your main ingredient. Inside the "example-component" folder, create a new TypeScript file called index.tsx.
Step 3: Seasoning the Component
Now comes the fun part, seasoning our ingredients. Open the newly created index.tsx file and create an index.html file and add your component's code. Just like seasoning a dish to taste, this code will give our component its unique flavor.
Index.tsx
import React from 'react';
import ReactDOM from 'react-dom';
const OptionsContext = React.createContext(null);
export default function createExternalRoot(container) {
return {
render(context) {
ReactDOM.render(
<OptionsContext.Provider value={context.options}>
<OptionsContext.Consumer>
{options => (
<>
<h2 style={{ color: context.theme.palette.primary.main }}>
Example Component
</h2>
<p>
Example Component, Sitecore Content Hub
</p>
</>
)}
</OptionsContext.Consumer>
</OptionsContext.Provider>,
container
);
},
unmount() {
ReactDOM.unmountComponentAtNode(container);
},
};
}
Index.html
<!DOCTYPE html>
<html>
<head>
<title>Example Component</title>
</head>
<body>
<div id="app"></div>
<div id="myElement">.</div>
<script type="module">
import createExternalRoot from '/src/components/example-component/index.tsx';
const rootElement = document.querySelector("#app");
const component = createExternalRoot(rootElement);
const mockContext = {
theme: {
palette: {
primary: {
main: "#000000"
}
}
}
};
component.render(mockContext);
</script>
</body>
</html>
Step 4: Cooking the Component
With our ingredients prepped and seasoned, it's time to cook. Open your terminal or command line interface, navigate to the "Sitecore.CH.ExternalComponents.React" folder, and start the build process. After the build process completes, just like letting a dish simmer, we'll start our development server.
npm run build
Step 5: Taste Test
Like tasting a dish to ensure it's cooked to perfection, we'll validate our components. Navigate to the development server URL, and you should see the transpiled JavaScript code for your component.
https://localhost:5000/dist/example-component.js
Step 6: Plating the Dish
In the culinary world, presentation is everything. Similarly, in our digital kitchen, we need to upload our beautifully cooked components to the Content Hub. Navigate to the Sitecore Content Hub management interface and select "Portal Assets". Upload the JavaScript file that we cooked up - "example-component.js".
Step 7: Serving the Dish
Finally, it's time to serve our dish. In our case, this means adding the external component to a Content Hub page. Navigate to the page where you want to add the external component, add it, and select the portal asset you just uploaded.
Additional Steps: Taste before you serve
Let's talk about debugging react components in our next blog.
In our next blog, we will convert an Existing Sitecore Content Hub 4.1 external component to a react component. And have a deep dive into how we debug these components.
