Skip to main content

Installation

Getting started with Refract is straightforward. In just a few minutes, you'll have a reactive application up and running with hot reloading and all the modern development tools you need.

This guide will walk you through creating a new Refract project from scratch. If you prefer to add Refract to an existing project, skip to the "Add to Existing Project" section.

What You'll Need​

Before we start, make sure you have:

  • Node.js 19 or higher - Refract uses modern JavaScript features
  • A package manager - npm (comes with Node.js), yarn, or pnpm
  • A code editor - VS Code, WebStorm, or your favorite editor
  • Basic JavaScript knowledge - If you know React, you'll feel right at home

Don't worry if you're new to modern JavaScript - Refract is designed to be beginner-friendly while still being powerful for experienced developers.

Step-by-Step Setup​

Step 1: Create Your Project Directory​

First, let's create a new directory for your Refract application:

Create Project Directory
mkdir my-refract-app
cd my-refract-app

This creates a new folder called my-refract-app and navigates into it. You can replace my-refract-app with whatever you'd like to name your project.

Step 2: Initialize Your Project​

Initialize a new Node.js project with a package.json file:

Initialize Package.json
npm init -y

The -y flag accepts all the default options. You can always edit the package.json file later to customize your project details.

Step 3: Install Refract and Dependencies​

Now let's install Refract and the development tools you'll need:

Install with npm
# Install Refract
npm install refract-js

# Install development dependencies
npm install --save-dev vite @vitejs/plugin-react

What we just installed:

  • refract-js - The core Refract library for building reactive applications
  • vite - A fast build tool that provides hot reloading and optimized builds
  • @vitejs/plugin-react - Enables JSX support and React-like features in Vite

Step 4: Configure Your Development Environment​

First, let's add the necessary scripts to your package.json file:

package.json - Add Scripts
{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}

Next, create a Vite configuration file to enable JSX support:

vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  server: {
    port: 3000,
    open: true
  }
});

Adding Refract to an Existing Project​

If you want to add Refract to an existing project instead of creating a new one:

  1. Install Refract: npm install refract-js
  2. Install Vite and React plugin: npm install --save-dev vite @vitejs/plugin-react
  3. Create a vite.config.js file with the React plugin
  4. Update your build scripts to use Vite
  5. Start using Refract components in your existing codebase

Troubleshooting​

Port already in use? If port 3000 is busy, Vite will automatically try the next available port (3001, 3002, etc.).

Module not found errors? Make sure you've installed all dependencies and that your file paths are correct.

JSX not working? Ensure you have the @vitejs/plugin-react plugin installed and configured in your vite.config.js.

Need more help? Check out our troubleshooting guide or join our community.