Skip to main content

⚛️ React + ⚡ Vite

This guide will help you set up a frontend project using React 18, Vite and MUI v6. It covers creating the project, folder structure, running, building and publishing the app.

📺

Video Tutorial

Build a Real-World Mortgage Calculator! 🏠

Ready to move beyond the basics? This tutorial takes you step-by-step through building a practical, interactive Mortgage Calculator Dart. By the end of it, you'll master:

  • 🏗️ Creating a real component from the hyperDart template
  • 🎨 Designing an interactive, dynamic user interface
  • ⚙️ Handling complex user inputs and state management
  • 🧮 Performing and displaying live mortgage calculations
  • 🧩 Structuring your components for real-world scenarios

This guide will help you set up a frontend project using React 18, Vite and MUI v6. It covers creating the project, folder structure, running, building and publishing the app.

📦 Create a New Template​

Run the following command to generate a new project template:

npm create hyper-dart@latest <componentName>
React + Vite + Hono Setup

During setup, choose Framework: React, and then select the variant React (JavaScript + Vite).

📂 Folder Structure​

This will generate the following folder structure:

Folder Structure
my-sandbox-app/
│
├── src/ # Main source directory
│ │
│ ├── frontend/ # Frontend (React + Vite) source code
│ │ ├── index.jsx # React app entry point
│ │ ├── NewComponent.jsx # Your frontend app code starts here
│ │
│ ├── sandbox/ # Sandbox or testing directory (for experiments)
│ ├── main.jsx # entry point that renders your root component within an Iframe for local development
├── hyperdart.config.js # HyperDart-specific configuration file
├── index.html # Main HTML template (used by Vite)
├── package.json # Root project package definition
├── README.md # Project documentation
├── resource.json # Resource configuration or metadata
├── searchData.json # Local search dataset or cache
├── vite.config.js # Vite configuration file

🧩 Explanation of Key Sections​

🔹 src/frontend/​

Houses the React app code. index.jsx serves as the app’s entry point, while NewComponent.jsx is an example component.

🔹 sandbox/​

A safe experimental area to test new components or configurations without affecting production code.


⚙️ Quick Start​

  1. Install dependencies:

    npm install
  2. Run frontend:

    npm start

Your React + Vite frontend is now live and ready for local development or HyperDart integration.


💻 Frontend (React + Vite)​

index.html
<!doctype html>
<html lang="en">

<head>
<meta charset="UTF-8" />
<link rel="icon" type="image/svg+xml" href="/vite.svg" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>hD</title>
</head>

<body>
<div id="root"></div>
<script type="module" src="/src/sandbox/main.jsx"></script>
</body>

</html>
Package.json
{
"name": "@hyperdart/sample-app",
"version": "1.0.0",
"source": "src/frontend/index.jsx",
"main": "dist/index.umd.js",
"module": "dist/index.modern.js",
"private": false,
"type": "module",
"devDependencies": {
"@emotion/react": "^11.7.1",
"@emotion/styled": "^11.6.0",
"@hyperdart/backend": "^2.0.2",
"@hyperdart/sandbox": "^2.0.0",
"@mui/icons-material": "^6.0.0",
"@mui/lab": "^6.0.0-beta.12",
"@mui/material": "^6.0.0",
"@vitejs/plugin-react": "^4.3.4",
"react": "18.3.1",
"react-dom": "18.3.1",
"vite": "^6.0.11",
"rollup-plugin-visualizer": "^5.12.0",
"vite-plugin-css-injected-by-js": "^3.5.2"
},
"dependencies": {
"@hyperdart/frontend": "^2.0.0"
},
"peerDependencies": {
"@emotion/react": "^11.7.1",
"@emotion/styled": "^11.6.0",
"@mui/icons-material": "^6.0.0",
"@mui/lab": "^6.0.0-beta.12",
"@mui/material": "^6.0.0",
"react": "18.3.1",
"react-dom": "18.3.1",
"react-router-dom": "^6.14.0"
},
"scripts": {
"start": "vite",
"build": "vite build"
},
"files": ["hyperdart.config.js", "dist", "resource.json"],
"publishConfig": {
"registry": "https://dev-registry.hyperdart.com"
}
}
src/frontend/index.jsx

The frontend React app code goes into NewComponent.jsx, which is wrapped inside the withHD Higher-Order Component (HOC).
This HOC must not be removed, as it is essential for enabling all functionalities of the HyperDart Sandbox app, both in local development and in production environments.

The withHD wrapper provides:

  • Context integration (themes, routing, and shared state)
  • Communication with the HyperDart framework
  • Proper handling of sandbox behaviors and embedded app logic
import NewComponent from "./NewComponent";
import { withHD } from "@hyperdart/frontend";

export default withHD(NewComponent);
src/frontend/NewComponent.jsx
import React from "react";
import { Typography } from "@mui/material";

function NewComponent(props) {
return (
<div>
<Typography variant="caption">hyperDart New Component</Typography>
</div>
);
}

export default NewComponent;
resource.json

This schema provides a fully generic structure for querying any type of resource, such as cars, electronics, real estate, jobs, or products. It is designed as a placeholder that can be customized for your domain.
See resource details

vit.config.json

Your viteConfig.js on setup looks like this:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { visualizer } from 'rollup-plugin-visualizer';
import pkg from './package.json';
import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js';
import hdConfig from './hyperdart.config';
import hDBackend from '@hyperdart/backend';

function createDartFramePlugin(hdConfig, pkg) {
const baseURL = hdConfig?.client?.baseURL || "/";
const updatedConfig = {
...hdConfig,
client: {
...hdConfig.client,
location: '/' + pkg.source,
},
};

return {
name: 'vite-plugin-dart-frame',
configureServer(server) {
server.middlewares.use(baseURL, async (req, res, next) => {
try {
const rawHtml = await hDBackend.createDartFrame(updatedConfig, null);
const html = await server.transformIndexHtml(req.originalUrl, rawHtml);
res.statusCode = 200;
res.setHeader("Content-Type", "text/html");
res.end(html);
} catch (e) {
server.ssrFixStacktrace(e);
next(e);
}
});


},
};
}

export default defineConfig(({ command }) => {
const isProduction = command === 'build';

return {
// base: hdConfig.client.baseURL,
plugins: [
react({
jsxRuntime: 'automatic',
}),
createDartFramePlugin(hdConfig, pkg),
cssInjectedByJsPlugin(),
visualizer(),
],
define: {
'process.env.NODE_ENV': JSON.stringify(isProduction ? 'production' : 'development'),
},
server: {
cors: true,
headers: {
"Access-Control-Allow-Origin": "*",
},
proxy: {
'/nodeapi': {
target: 'https://dev.hyperdart.com',
changeOrigin: true,
secure: true,
},
'/c': {
target: 'https://dev.hyperdart.com',
changeOrigin: true,
secure: true,
},
},
},
build: {
lib: {
entry: pkg.source,
name: pkg.umdName || 'HD' + pkg.name,
fileName: 'index.modern',
formats: ['es'],
},
},
};
});



hyperdartConfig.js

Please find the details on configuration file here:
See details


🎨 Sandbox​

Tests new components in local without affecting production code.

main.js

Entry point that renders your root component within an Iframe for local development

import './index.css';
import React from 'react';
import { createRoot } from 'react-dom/client';
import { HDSandbox } from '@hyperdart/sandbox';
import hDConfig from '../../hyperdart.config';
import defaultSearchData from '../../searchData.json';
import resourceJson from '../../resource.json'

const container = document.getElementById('root');
const root = createRoot(container);
root.render(<HDSandbox config={hDConfig} searchData={defaultSearchData} resource={resourceJson}/>);

📦 Tools & Frameworks​

  • Vite
  • React
  • MUI
  • Node.js

🚀 Publishing the Fronted App​

  1. Build frontend:
    npm run build
  2. Update version:
    npm version patch
  3. Publish:
    npm publish

✅ Publish Validation​

Publishing is authenticated — make sure your registry token is set (see Publish) before running npm publish.

When you publish, the registry validates your hyperdart.config.js and rejects the package if any check fails:

CheckRequirement
client.locationFile must exist in the published package (e.g. dist/index.modern.js)
server.locationIf a server block is present, the file must exist in the published package
server.configPathIf a server block is present, the file must exist in the published package
triggers.keywordsMust not be empty and must not contain empty strings
query_format.regexMust not be empty and must not contain empty strings
demoVideoMust be a valid YouTube link
githubMust be a valid GitHub link
// hyperdart.config.js
export default {
// ...
demoVideo: 'https://www.youtube.com/watch?v=<video-id>',
github: 'https://github.com/<user>/<repo>',
}