LocatorJS Documentation

LocatorJS works automatically in development mode for most modern stacks (NextJS, Create React App, Vite, etc.).

To function correctly, your project must include babel-plugin-transform-react-jsx-source (often included via babel-preset-react). Non-Babel stacks use similar alternatives to provide source information. If your environment does not provide this, you must set it up manually.

The loader enables component location tracking by using Babel's transform API to apply the @locator/babel-jsx plugin to JSX/TSX files.

It works by:

1. Parsing JSX/TSX files via Babel.
2. Adding data-locatorjs attributes containing the full file path and location (e.g., data-locatorjs="/path/to/file.tsx:line:column").
3. Returning transformed code with sourcemaps.

Key Benefits:

• Server Components Support: Unlike other methods, it does not require window.__LOCATOR_DATA__, making it compatible with React Server Components where JavaScript execution is limited.
• Automatic Filtering: It automatically skips node_modules and middleware files.
• Framework Compatibility: Works with React, Preact, and SolidJS.

Hot Module Replacement (HMR) in this template does not preserve local component state by default due to the inherent complexities of state preservation in Svelte HMR plugins.

To ensure important data is not lost when a component reloads during development, move that state into an external Svelte store. External stores reside outside the component lifecycle and are not replaced when the component is re-rendered via HMR.

// store.js
// An extremely simple external store
import { writable } from 'svelte/store'
export default writable(0)

To use LocatorJS with Next.js 15+ using Turbopack, add the loader to the turbopack.rules section in your next.config.ts or next.config.js. Target .tsx and .jsx files.

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  turbopack: {
    rules: {
      "**/*.{tsx,jsx}": {
        loaders: [
          {
            loader: "@locator/webpack-loader",
            options: {
              env: "development",
            },
          },
        ],
      },
    },
  },
};

export default nextConfig;

This template provides a minimal starting point for developing with Svelte using Vite. It is designed to provide a good developer experience with Hot Module Replacement (HMR) and Intellisense while remaining lightweight.

If you require a full-featured framework with routing and serverless capabilities, consider using SvelteKit instead. This template is structured similarly to SvelteKit to facilitate easy migration if your project requirements grow.

To use this template, clone the repository and install dependencies using your preferred package manager. While a pnpm-lock.yaml is included because dependencies are maintained via pnpm, you can use npm or yarn instead. If you use a different package manager, you can safely remove the pnpm-lock.yaml file.

$ npm install # or pnpm install or yarn install

Install the @locator/webpack-loader package as a development dependency using your preferred package manager.

npm install --save-dev @locator/webpack-loader
# or
yarn add -D @locator/webpack-loader
# or
pnpm add -D @locator/webpack-loader

To start the development server for this Next.js project, use your preferred package manager to run the dev script. Once running, you can view the application at http://localhost:3000.

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

For Next.js projects using Webpack (or those using SWC), inject the loader into the webpack configuration function within next.config.js. Ensure the loader is only applied to the client-side (!isServer) to avoid issues with server-side rendering.

module.exports = {
  webpack: (config, { isServer }) => {
    if (!isServer) {
      config.module.rules.push({
        test: /\.(tsx|ts|jsx|js)$/,
        exclude: /node_modules/,
        use: [
          {
            loader: "@locator/webpack-loader",
            options: {
              env: "development",
            },
          },
        ],
      });
    }
    return config;
  },
};