Skip to main content

Development Server

The development server is your best friend while building Refract applications. It provides instant feedback, hot reloading, and powerful debugging tools that make development fast and enjoyable.

Think of it as your coding companion - it watches your files, automatically refreshes your browser when you make changes, and helps you catch errors before they become problems.

Why Use a Development Server?​

When you're building an application, you want to see your changes immediately. The development server provides:

  • Instant Updates: See your changes in the browser without manual refreshes
  • Error Reporting: Clear error messages right in your browser
  • Fast Builds: Optimized for speed during development
  • Debugging Tools: Source maps and development-friendly code

It's the difference between having to manually refresh your browser every time you make a change versus having your changes appear instantly.

Starting the Development Server​

The simplest way to start your development server is with a single command:

Start Development Server
npm run dev

This starts your development server on http://localhost:3000 (or the next available port). Your browser should automatically open to show your application.

Advanced Server Options​

You can customize how the development server runs:

Development Server Options
# Start on a specific port
npm run dev -- --port 4000

# Allow network access (useful for testing on mobile devices)
npm run dev -- --host

# Start with HTTPS (useful for testing secure features)
npm run dev -- --https

# Combine options
npm run dev -- --port 4000 --host --open

Debugging Techniques​

State Debugging​

Debug reactive state changes effectively:

State Debugging Patterns
const useDebugState = createOptic((lens, initialValue, name) => {
  const state = lens.useRefraction(initialValue);

  // Log all state changes in development
  lens.useEffect(() => {
    if (import.meta.env.DEV) {
      console.log(`[${name}] State changed:`, state.value);
    }
  }, [state.value]);

  return {
    value: state.value,
    set: (newValue) => {
      if (import.meta.env.DEV) {
        console.log(`[${name}] Setting state:`, newValue);
      }
      state.set(newValue);
    }
  };
});

const MyComponent = createComponent(({ lens }) => {
  const counter = lens.useOptic(useDebugState, 0, 'Counter');

  return (
    <div>
      <p>Count: {counter.value}</p>
      <button onClick={() => counter.set(counter.value + 1)}>
        Increment
      </button>
    </div>
  );
});

Debugging Tips:

  • Use import.meta.env.DEV to only log in development
  • Add meaningful names to your debug logs
  • Use browser DevTools to set breakpoints
  • Consider using React DevTools for component inspection