Skip to main content

Quickstart

In this guide you learn how to create a Refract app in less than five minutes:

Step 1 : Create your project structure​

Let's create the basic files you need for a Refract app:

Create Project Files
# Create source directory
mkdir src

# Create main files
touch src/main.js src/App.js index.html

Step 2: Set up your HTML template​

Create your main HTML file:

index.html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Refract App</title>
</head>
<body>
  <div id="root"></div>
  <script type="module" src="/src/main.js"></script>
</body>
</html>

Step 3: Create your first component​

Now let's create your first Refract component:

src/App.js
import { createComponent } from "refract";

const App = createComponent(({ lens }) => {
  const message = lens.useRefraction("Hello, Refract!");

  return (
    <div style={{ padding: '20px', fontFamily: 'Arial, sans-serif' }}>
      <h1>{message.value}</h1>
      <p>Welcome to your first Refract application!</p>
      <button
        onClick={() => message.set("You clicked the button!")}
        style={{
          padding: '10px 20px',
          backgroundColor: '#0066cc',
          color: 'white',
          border: 'none',
          borderRadius: '4px',
          cursor: 'pointer'
        }}
      >
        Click me!
      </button>
    </div>
  );
});

export default App;

Step 4: Create your Application entry point​

Create the main JavaScript file that starts your app:

src/main.js
import { createApp } from "refract";
import App from "./App.js";

const app = createApp(App);
app.mount("#root");

Step 5: Start your development server​

Now for the exciting part - let's see your app in action. Run the development server:

Start with npm
npm run dev

You should see output similar to this:

  VITE v4.4.5  ready in 123 ms

  ➜  Local:   http://localhost:3000/
  ➜  Network: use --host to expose

Step 6: View your application​

Open your browser and navigate to http://localhost:3000. You should see:

  • A heading that says "Hello, Refract!"
  • A welcome message
  • A blue button that changes the heading when clicked

Congratulations! 🎉 You've successfully created your first Refract app.

What you've built​

Your new Refract app includes:

  • Reactive state - The message changes when you click the button
  • Hot reloading - Changes to your code appear instantly in the browser
  • Modern development tools - Vite provides fast builds and great developer experience
  • Component-based architecture - Your UI is built with reusable components

Next steps​

Now that you have Refract installed and running, here's what you can explore next:

  • Learn the basics - Understand Refract's core concepts
  • Development - Learn about development tools and debugging
  • Build - Get your app ready for production
  • Deploy - Deploy your app on hosting platform