# @paciolan/remote-component
> Dynamically load a React Component from a URL
Latest version **2.14.0** (published 2026-07-27) · MIT license · 0 weekly downloads
## Install
```sh
npm install @paciolan/remote-component
pnpm add @paciolan/remote-component
yarn add @paciolan/remote-component
bun add @paciolan/remote-component
```
## Health
**Score 55/100 (C)** — status: active.
Positive: no vulnerabilities; recently updated; high maintenance score.
Warnings: low downloads; no types; no esm support.
## Facts
| | |
|---|---|
| Version | 2.14.0 |
| Published | 2026-07-27 |
| First published | 2019-03-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 207.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 641 |
| Author | Paciolan |
| Maintainers | paciolan |
## Links
- npm: https://www.npmjs.com/package/@paciolan/remote-component
- Repository: https://github.com/Paciolan/remote-component
- Homepage: https://github.com/Paciolan/remote-component#readme
- Issues: https://github.com/Paciolan/remote-component/issues
- npm.io page: https://npm.io/package/@paciolan/remote-component
## Dependencies (1)
- [@paciolan/remote-module-loader](https://npm.io/package/@paciolan/remote-module-loader.md) ^3.2.2
## Recent versions
- 2.14.0 (latest) — 2026-07-27
- 2.13.2 — 2026-04-06
- 2.13.1 — 2026-03-03
- 2.13.0 — 2023-01-18
- 2.12.1 — 2022-01-19
- 2.12.0 — 2021-11-11
- 2.11.0 — 2021-01-07
- 2.10.3 — 2020-12-18
- 2.10.2 — 2020-12-10
- 2.10.1 — 2020-12-03
- 2.10.0 — 2020-12-03
- 2.9.0 — 2020-11-24
- 2.8.1 — 2020-09-17
- 2.8.0 — 2020-09-02
- 2.7.2 — 2020-03-31
- … 31 more at https://npm.io/package/@paciolan/remote-component/versions
## README
# Remote Component 
Load a React Component from a URL at runtime.
## Table of Contents
- [What is a Remote Component?](#what-is-a-remote-component)
- [Install](#install)
- [Dependencies](#dependencies)
- [Injecting Dependencies with Webpack](#injecting-dependencies-with-webpack)
- [Injecting Dependencies without Webpack](#injecting-dependencies-without-webpack)
- [Custom Fetcher](#custom-fetcher)
- [Adding a Remote Component to a React App](#adding-a-remote-component-to-a-react-app)
- [Handling Load Errors](#handling-load-errors)
- [Render Props](#render-props)
- [React Hooks](#react-hooks)
- [Creating a Remote Component](#creating-a-remote-component)
- [Remote Component Starter Kit](#remote-component-starter-kit)
- [Creating a Remote Component with Webpack](#creating-a-remote-component-with-webpack)
- [Create React App (CRA)](<#create-react-app-cra>)
- [Server Side Rendering with Next.js](#server-side-rendering-with-nextjs)
- [getServerSideProps](#getserversideprops)
- [Calling getServerSideProps from Next.js](#calling-getserversideprops-from-nextjs)
- [How it works](#how-it-works)
- [Content Security Policy (CSP)](#content-security-policy-csp)
- [Alternatives](#alternatives)
- [Roadmap](#roadmap)
- [Caveats](#caveats)
## What is a Remote Component?
A Remote Components is loaded at runtime from a URL. It is used in the same way any other React Component is used.
```javascript
const url =
"https://raw.githubusercontent.com/Paciolan/remote-component/master/examples/remote-components/HelloWorld.js";
const HelloWorld = ({ name }) => ;
const Container = (
<>
);
```
## Install
```bash
npm install @paciolan/remote-component
```
## Dependencies
The React Application and Remote Component can share dependencies. The dependencies must be configured explicitly.
Shared dependencies in the Remote Component must be marked as `external` so they are not bundled in the output.
All shared dependencies must be provided by the React Application.
### Injecting Dependencies with Webpack
Create a file in the root of your React Application called `remote-component.config.js`. Some frameworks like Create React App (CRA) might need this file placed inside the `src` directory. The location can be changed inside of `webpack.config.js`.
This file will supply the Remote Components with their needed external dependencies.
```javascript
/**
* Dependencies for Remote Components
*/
module.exports = {
resolve: {
react: require("react")
}
};
```
Add a Webpack `alias` inside of `webpack.config.js` so the RemoteComponent can load this file.
```javascript
module.exports = {
resolve: {
alias: {
"remote-component.config.js": __dirname + "/remote-component.config.js"
}
}
};
```
### Injecting Dependencies without Webpack
Projects without webpack can still use a Remote Component through a manual configuration.
Follow the directions in [Injecting Dependencies with Webpack](#injecting-dependencies-with-webpack) to create the `remote-component.config.js`.
Create `src/RemoteComponent.js` and import the dependencies from `remote-component.config.js`.
```javascript
import {
createRemoteComponent,
createRequires
} from "@paciolan/remote-component";
import { resolve } from "../remote-component.config.js";
const requires = createRequires(resolve);
export const RemoteComponent = createRemoteComponent({ requires });
```
Then you will change the `import` for `RemoteComponent` to point to this new file.
```
import { RemoteComponent } from "./RemoteComponent";
```
## Custom Fetcher
The Custom Fetcher is a feature for advanced users only. It exposes the `fetcher` from the underlying [@paciolan/remote-module-loader](https://github.com/Paciolan/remote-module-loader).
Refer to [@paciolan/remote-module-loader](https://github.com/Paciolan/remote-module-loader) documentation for more information about how to use the `fetcher`.
```javascript
const fetcher = url => axios.get(url).then(request => request.data);
fetchRemoteComponent({ url, requires, fetcher });
```
## Adding a Remote Component to a React App
Import `RemoteComponent` from either `@paciolan/remote-component` or your custom `./src/RemoteComponent.js` (depending on your setup).
It is recommended to wrap `` in a component for better naming and separation. This is optional.
Pass the `url` to the ``.
Use a `RemoteComponent` like a regular React Component.
```javascript
import React from "react";
import ReactDOM from "react-dom";
import { RemoteComponent } from "@paciolan/remote-component";
const element = document.getElementById("app");
const url = "https://raw.githubusercontent.com/Paciolan/remote-component/master/examples/remote-components/HelloWorld.js"; // prettier-ignore
const HelloWorld = props => ;
ReactDOM.render(, element);
```
### Handling Load Errors
When the `url` fails to load (or loads without a `default` export), the `RemoteComponent` renders a generic error message by default. Pass `errorFallback` to render something else instead (or `null` to render nothing), and `onLoadError` to be notified of the failure — for example to log it or surface a toast. `onLoadError` is called once per failed load, even when a `render` prop controls the output.
```javascript
const HelloWorld = props => (
Loading...}
errorFallback={Could not load HelloWorld.
}
onLoadError={err => console.error("HelloWorld failed to load", err)}
{...props}
/>
);
```
### Render Props
In the case you need more control over the error or rendering, you can use a `render` prop.
```javascript
const HelloWorld = props =>
err ? {err.toString()}
:
}
/>
);
```
### React Hooks
If you need even more control, you can create a custom `useRemoteComponent` React Hook.
Start by creating `src/useRemoteComponent.js`.
```javascript
import {
createRequires,
createUseRemoteComponent
} from "@paciolan/remote-component";
import { resolve } from "../../remote-component.config.js";
const requires = createRequires(resolve);
export const useRemoteComponent = createUseRemoteComponent({ requires });
```
Next, use the custom hook.
```javascript
import { useRemoteComponent } from "./useRemoteComponent";
const url = "https://raw.githubusercontent.com/Paciolan/remote-component/master/examples/remote-components/HelloWorld.js"; // prettier-ignore
const HelloWorld = props => {
const [loading, err, Component] = useRemoteComponent(url);
if (loading) {
return Loading...
;
}
if (err != null) {
return Unknown Error: {err.toString()}
;
}
return ;
};
```
Named import example
```javascript
import { useRemoteComponent } from "./useRemoteComponent";
const url = "https://raw.githubusercontent.com/Paciolan/remote-component/master/examples/remote-components/HelloWorld.js"; // prettier-ignore
const HelloWorld = props => {
const [loading, err, Component] = useRemoteComponent(url, "customImportName");
if (loading) {
return Loading...
;
}
if (err != null) {
return Unknown Error: {err.toString()}
;
}
return ;
};
```
## Creating a Remote Component
Creating a Remote Component involves creating a CommonJS module. That module should have `react` and other shared dependencies excluded from the bundle. It should also already be transpiled for browser support.
### Remote Component Starter Kit
Clone the [remote-component-starter](https://github.com/Paciolan/remote-component-starter) for a ready to go project.
### Creating a Remote Component with Webpack
The Remote Component must be exported.
```javascript
import React from "react";
const RemoteComponent = () => {
return Hello Remote World!
;
};
export default RemoteComponent;
```
Inside of the `webpack.config.js`, the `libraryTarget` must be set to `commonjs`.
Any shared dependencies must be added as an `external`. This will prevent them from being bundled in the library.
```javascript
module.exports = {
output: {
libraryTarget: "commonjs"
},
externals: {
react: "react"
}
};
```
Inside of the `package.json`, set `main` to the webpack entrypoint. This will probably be `dist/main.js`.
Shared dependencies you have marked as `external` should be removed from `dependencies` and added to both `devDependencies` (so they are available during development) and `peerDependencies` (so the upstream package knows it is responsible for installation).
The dependency version should match the version inside the React Application.
```javascript
{
"main": "dist/main.js",
"devDependencies": {
"react": "^16.8"
},
"peerDependencies": {
"react": "^16.8"
}
}
```
## Create React App (CRA)
Start a new Create React App app or use an existing one. This is a React Application that will import Remote Components.
```bash
$ npx create-react-app my-react-app
$ cd my-react-app
```
Create `src/remote-component.config.js`. note: CRA requires this file to be placed inside of `src`.
```javascript
/**
* These dependencies will be made available to the Remote Components.
*/
module.exports = {
resolve: {
react: require("react")
}
};
```
Create `src/RemoteComponent.js`. The `RemoteComponent` must manually be created because CRA does not provide access to `webpack.config.js` without ejection.
```javascript
import {
createRemoteComponent,
createRequires
} from "@paciolan/remote-component";
import { resolve } from "./remote-component.config.js";
const requires = createRequires(resolve);
export const RemoteComponent = createRemoteComponent({ requires });
```
You may see the following warning. It is safe to ignore.
```
Compiled with warnings.
./node_modules/@paciolan/remote-component/dist/getDependencies.js
Module not found: Can't resolve 'remote-component.config.js' in '/et/repo/cra-remote-component/node_modules/@paciolan/remote-component/dist'
```
You can get rid of this warning by directly including the files. This is unsafe as these files paths could change.
```javascript
import { createRemoteComponent } from "@paciolan/remote-component/dist/createRemoteComponent";
import { createRequires } from "@paciolan/remote-component/dist/createRequires";
import { resolve } from "./remote-component.config.js";
const requires = createRequires(resolve);
export const RemoteComponent = createRemoteComponent({ requires });
```
## Server Side Rendering with Next.js
Server Side Rendering with Next.js is currently (EXPERIMENTAL).
Follow the steps in [Injecting Dependencies with Webpack](#injecting-dependencies-with-webpack) to create the `remote-component.config.js`.
### getServerSideProps
Add a `getServerSideProps` method to your Remote Component. This follows the Next.js pattern.
```javascript
import React from "react";
const Person = ({ data }) => {
const entries = Object.entries(data);
const rows = entries.map(([key, value], i) => (
| {key} |
{value} |
));
return ;
};
const getServerSideProps = async ({ data }) => {
const response = await fetch(`https://swapi.dev/api/people/${data.id}`);
return await response.json();
};
Person.getServerSideProps = getServerSideProps;
export default Person;
```
## Calling getServerSideProps from Next.js
Modify the Next.js page that will contain the Remote Component.
Add these imports. Notice how `getServerSideProps` is renamed to `getProps` to prevent conflicts with the Next.js function of the same name.
```javascript
import {
createRequires,
fetchRemoteComponent,
getServerSideProps as getProps
} from "@paciolan/remote-component";
import dynamic from "next/dynamic";
import config from "../remote-component.config";
```
Create the `requires` for shared dependencies that will be provided to the Remote Component. Then pass `url` and `requires` into `fetchRemoteComponent`. Wrap this inside of `dynamic`.
```javascript
const requires = createRequires(config.resolve);
const url = "http://localhost:5000/MyRemoteComponent.js";
const MyRemoteComponent = dynamic(() =>
fetchRemoteComponent({ url, requires })
);
```
Create Next.js's `getServerSideProps` function. Pass the Next.js `context` (if the component needs the context) as well as any data in as `context` when calling `getProps`.
```javascript
export async function getServerSideProps(context) {
const data = { id: 1 };
const myData = await getProps({
url,
requires,
context: { ...context, data }
});
return { props: { myData } };
}
```
The `props` returned from Next.js's `getServerSideProps` function will be passed into the `props`. You can then use those `props` to send the data into the Remote Component.
```javascript
export default function MyPage(props) {
return (
);
}
```
## How it works
The `RemoteComponent` React Component takes a `url` as a prop. The `url` is loaded and evaluated. This file must be a valid CommonJS Module that exports the component as `default`.
While the `url` is loading, the `fallback` will be rendered. This is a similar pattern to [`React.Suspense`](https://reactjs.org/blog/2018/10/23/react-v-16-6.html). If no `fallback` is provided, then nothing will be rendered while loading.
Once loaded, there will either be an `err` or a `Component`. The rendering will first be handled by the `render` callback function. If there is no `render` callback and `err` exists, the `errorFallback` is rendered when one was provided, otherwise a generic message will be shown. When `err` exists, `onLoadError` is also called once with the error.
The `Component` will be rendered either to the `render` callback if one exists, otherwise it will be rendered as a standard component.
## Content Security Policy (CSP)
Sites with a content_security_policy header set are likely to not work. CSP puts a restriction on using new Function, which remote-module-loader relies upon.
This library depends on [@paciolan/remote-module-loader](https://github.com/Paciolan/remote-module-loader), which does not support CSP. Until CSP is supported in [@paciolan/remote-module-loader](https://github.com/Paciolan/remote-module-loader), it cannot be supported.
[Read more on CSP](https://developer.chrome.com/extensions/contentSecurityPolicy)
## Alternatives
- [Webpack Module Federation](https://webpack.js.org/concepts/module-federation)
## Roadmap
- Add support for multiple components import from a single URL.
- Add TypeScript support
## Caveats
There are a few things to be aware of when using `RemoteComponent`.
- Calls to a `RemoteComponent` add an additional HTTP call.
- Dependencies could be included twice. If a dependency is included in the library and also in the Web App. This could have unknown effects.
- The external dependencies of the library and Web Application must match. This makes upgrading 3rd party libraries that have breaking changes more complex.
- The `RemoteComponent` and web application's browser targets must match. If your React App targets IE11, but the Remote Component does not, then it will not work in IE11.
- Debugging could be more complicated as source map support does not (yet) exist.
- Nested `RemoteComponents` can get exponentially hard to manage (dependencies) and develop (running multiple repositories at the same time for localhost)
- [Content Security Policy (CSP)](<#content-security-policy-(csp)>) is not supported.
## Contributors
Joel Thoms (https://twitter.com/joelnet)
Icons made by smalllikeart from www.flaticon.com
Icons made by turkkub from www.flaticon.com
Icons made by Freepik from www.flaticon.com
---
_Source: https://npm.io/package/@paciolan/remote-component · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._