Starting a Project¶
Here we assume that you are using either Cursor or VSCode with AI agents.
Emphasis here is on VSCode + Claude Code running in the VSCode extension.
From scratch¶
Wanna play around, maybe just do a frontend-only app and not worry about backends, databases, etc?
Let’s create a minimal scaffold. Create a new, empty directory for your project and start Claude Code in it:
mkdir my_cute_app
cd my_cute_app
claude
(or open my_cute_app as your workspace root folder in VSCode and start the Claude Code extension there)
Then tell Claude:
Please read
https://raw.githubusercontent.com/elsampsa/cutefront/main/vscode-configs/cute-project-init.md
and follow its instructions
That’s it! Claude creates the project scaffold, learns cutefront and tells you what to do next.
If you prefer to create the scaffold by hand, run this online initialization script in your (empty) project directory instead:
bash <(curl -sSL https://raw.githubusercontent.com/elsampsa/cutefront/main/new_project.bash)
Either way, you now have the necessary directory structure and the widget base library:
When you come back to the project later, start Claude Code in my_cute_app and give it the command /cute-frontend.
Now we can test how Claude Code and Cutefront perform in creating a webapp with some potential for global state mess. Try for example this prompt:
Hi! Let's create a single-page application: a frontend for an industrial visual quality control system.
There are three widget classes:
- A widget showing the status of the production line (statuses of conveyor belt, robotic arm and the polishing blade)
- A 2D height profile (colormap) widget of a sheet of some Very Expensive Sample Material
- A list widget of past, inspected height profiles. Each list item includes timestamp and a sample status (polished or not)
Here is some more information on the widget instances and interactions:
- There are two instances of the height profile widget
- The first height profile is always updated to the latest data received from the production line
- The second height profile corresponds to the sample user has clicked in the list of past height profiles. By default it is the latest sample from production line
- When user clicks on a height profile (either first or second one), the corresponding list item is chosen in the list
- When user clicks on a list item, the second height profile shows the corresponding height profile
- Each list item / sheet of Very Expensive Material has a sample status (polished or not) that is updated some time in the future
(when the blade has polished the sample succesfully)
As always with cutefront, for each widget class, please create corresponding test html files. Each test file should include
buttons for testing and one button that says "test all" which performs all unit tests on that widget.
No backends at this stage, but lets create mock datasources to simulate the actual backend.
The SPA application should go into "landing.html" and it should have a test-mode that can be invoked with URL-encoded parameters.
In test-mode, there should be an additional panel with buttons for "send new sample", "polish latest sample", i.e. buttons for simulating all core functions.
Please do the initial testing of the test htmls and the SPA using the "cute-browser" command.
Here is the layout for the SPA:
[first height profile ] [ status widget ]
[second height profile] [ list of height profs ]
Tip
If you want get philosophical, ask Claude Code why Cutefront doesn’t need a “Virtual DOM” :)
FastAPI Fullstack¶
Check out the FastAPI fullstack example:
git checkout https://github.com/elsampsa/fullstack-fastapi-cutefront
git submodule update --init --recursive
Now you have:
The original (pristine & untouched) FastAPI fullstack example as a submodule
Cutefront frontend has been built on top of the fullstack example
Custom docker compose files run the original fullstack example with Cutefront frontend
This is a ready-to-run all-included fullstack app. It is also the SOTA reference on Cutefront and FastAPI-based fullstack apps.
You can use the create-scaffold.bash script to create a stand-alone project stub without the original vite-frontend and submodular structures.