Getting Started
About 948 wordsAbout 3 min
2026-03-28
This guide will help you create your first Puppet application in 5 minutes.
Environment Requirements
Before starting, ensure your system meets the following requirements:
- Operating System: Windows 10 or higher
- .NET Runtime: .NET 10.0 or higher
- WebView2 Runtime: Usually installed with Edge browser. If not installed, download from Microsoft Official Website
Tip
The Puppet Framework will automatically check and prompt for installation of required runtime environments.
Creating Your First Application
1. Prepare Project Files
Create a new folder as your project directory:
mkdir MyFirstPuppetApp
cd MyFirstPuppetApp2. Create Main Page
Create an index.html file:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>My First Puppet Application</title>
<style>
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}
body {
font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
min-height: 100vh;
display: flex;
justify-content: center;
align-items: center;
color: white;
}
.container {
text-align: center;
padding: 40px;
background: rgba(255, 255, 255, 0.1);
backdrop-filter: blur(10px);
border-radius: 20px;
box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3);
}
h1 {
font-size: 2.5em;
margin-bottom: 20px;
}
p {
font-size: 1.2em;
margin-bottom: 30px;
}
button {
padding: 12px 24px;
font-size: 16px;
border: none;
border-radius: 8px;
background: white;
color: #667eea;
cursor: pointer;
transition: transform 0.2s, box-shadow 0.2s;
margin: 0 10px;
}
button:hover {
transform: translateY(-2px);
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2);
}
button:active {
transform: translateY(0);
}
.info {
margin-top: 20px;
font-size: 14px;
opacity: 0.8;
}
</style>
</head>
<body>
<div class="container">
<h1>🎭 Puppet Framework</h1>
<p>Welcome to the Puppet Framework!</p>
<button onclick="testWindow()">Window Control</button>
<button onclick="testSystem()">System Info</button>
<button onclick="testLog()">Test Log</button>
<div class="info" id="info">Click buttons to test functionality</div>
</div>
<script>
// Window control test
async function testWindow() {
try {
// Set opacity
await puppet.window.setOpacity(0.9);
// Show info
showInfo('Window opacity set to 90%');
// Restore after 2 seconds
setTimeout(async () => {
await puppet.window.setOpacity(1.0);
}, 2000);
} catch (error) {
showInfo('Error: ' + error.message);
}
}
// System info test
async function testSystem() {
try {
const sysInfo = await puppet.system.getSystemInfo();
showInfo('Operating System: ' + sysInfo.osName);
} catch (error) {
showInfo('Error: ' + error.message);
}
}
// Log test
function testLog() {
puppet.log.info('This is an info log');
puppet.log.warn('This is a warning log');
puppet.log.error('This is an error log');
showInfo('Logs output, check console');
}
// Show info
function showInfo(message) {
document.getElementById('info').textContent = message;
}
</script>
</body>
</html>3. Run Application
There are two ways to run a Puppet application:
Method 1: Bare Folder Mode (for development)
This is the recommended way during development, allowing you to see code changes in real-time:
# Assuming puppet.exe is in E:\puppet\puppet\bin\Debug\ directory
E:\puppet\puppet\bin\Debug\puppet.exe --nake-load "C:\MyFirstPuppetApp"Method 2: PUP File Mode (for distribution)
First create a PUP file:
E:\puppet\puppet\bin\Debug\puppet.exe --create-pup -i "C:\MyFirstPuppetApp" -o "C:\MyFirstPuppetApp.pup"Then run the PUP file:
E:\puppet\puppet\bin\Debug\puppet.exe --load-pup "C:\MyFirstPuppetApp.pup"4. Test Functionality
Click the buttons in the application to test the following features:
- Window Control: Window opacity will briefly change
- System Info: Display the current operating system name
- Test Log: Output logs of different levels to the console
Next Steps
Congratulations! You have successfully created your first Puppet application. Next steps:
- Deep Dive into API: View API Documentation to learn about all available features
- Window Control: Learn how to create borderless, transparent windows
- File Operations: Understand how to read and write local files
- Event System: Implement device plug/unplug, window events, and other monitoring
- System Functions: Get system information, simulate keystrokes, etc.
Common Questions
Q: How to create a borderless window?
A: Add the following code to your HTML:
// Set immediately after page load
window.addEventListener('DOMContentLoaded', async () => {
await puppet.window.setBorderless(true);
await puppet.window.setDraggable(true);
});For detailed instructions, refer to Window Control API.
Q: How to debug applications?
A: You can:
- Use browser developer tools (right-click in Puppet application -> Inspect)
- Use
puppet.log.info()and other methods to output logs - In bare folder mode, directly modify HTML files to see changes in real-time
Q: Can PUP files be encrypted?
A: Yes. Specify a password when creating a PUP file:
puppet.exe --create-pup -i "C:\MyProject" -o "C:\MyProject.pup" -p "mypassword"For detailed instructions, refer to PUP File Format.
Q: How to create a signed PUP file?
A: Use V1.2 format and puppet-sign tool:
# 1. Generate signing key pair
puppet-sign.exe --generate-signing-key --alias MyApp --key-size 2048
# 2. Create signed PUP file
puppet.exe --create-pup -i "C:\MyProject" -o "C:\MyProject.pup" -v 1.2 --certificate "app.crt" --private-key "app.key" --private-key-password "mypassword"Signed PUP files ensure application integrity and source trustworthiness. For detailed instructions, refer to Security Mechanisms and PUP File Format.
Q: How to make the application start automatically on boot?
A: Use the execute method of the Application API to create a shortcut:
await puppet.application.execute(
'cmd /c mkshortcut /target:"C:\\MyApp\\puppet.exe" /shortcut:"%APPDATA%\\Microsoft\\Windows\\Start Menu\\Programs\\Startup"'
);Related Resources
- Framework Introduction - Learn about Puppet's core features
- Architecture Design - Deep dive into framework internal principles
- Command Line Parameters - All command line option instructions
- API Documentation - Complete API reference manual
Getting Help
If you encounter issues during development:
- Check relevant sections of this documentation
- View API Documentation for specific usage
- Submit issues on GitHub Issues
Changelog
db86e-docs: add TypeScript type definitions documentationon
