React Getting Started

Starting from version 4.4.0.0, DEXTUploadX5 (hereinafter X5) supports React environments. To use X5 in React, use the dextuploadx5-react package.

This document explains the minimum configuration, based on a Node.js and Webpack environment, up to the point where the X5 list-type UI is created in the browser in a client-server separated structure. Since actual projects may differ in directory structure, routing, and deployment, this document covers only common concepts and required settings without depending on a specific sample structure.

Package roles

dextuploadx5-react: Provides the Provider, UI components, and control objects required to use X5 in React.
dextuploadx5-react-webpack: An auxiliary package that helps place X5 static resources into the project's static path more easily in a Webpack environment.
dextuploadx5-express-handler: A server-side handler package used to process X5 upload requests in an Express server.

This document only covers displaying the list-type UI on the screen. Actual upload/download processing and how to use dextuploadx5-express-handler are covered in separate documents.

Install packages

If the client and server are separate projects, install only the packages required by each one. (For packages required on the server, refer to the React > Upload document.)

# Client project
npm install react react-dom dextuploadx5-react
npm install -D html-webpack-plugin dextuploadx5-react-webpack

Place X5 static resources

The browser loads the scripts and resources required by X5 based on productPath. Therefore, the actual X5 product files must exist under that path.

In a Webpack environment, using dextuploadx5-react-webpack can simplify static resource placement.

# webpack.config.js example

import path from "path";
import { withDEXTUploadX5 } from "dextuploadx5-react-webpack";

const config = {
  entry: "./src/index.jsx",
  output: {
    publicPath: "/"
  }
};

// withDEXTUploadX5 automatically handles static resource placement.
export default withDEXTUploadX5(config, {
  publicDir: path.resolve("public"),
  dx5DirName: "dx5"
});

With the configuration above, the browser will generally access X5 resources through the /dx5/ path.

If you do not use the auxiliary package, you must copy the node_modules/dextuploadx5-react/dist/dx5 directory directly into the application's static file path.

Provide authKey and productPath

To use X5 components, wrap the components that use child X5 UI components with DEXTUploadX5Provider, and configure the auth key and productPath on DEXTUploadX5Provider.

import { useEffect, useState } from "react";
import { DEXTUploadX5Provider } from "dextuploadx5-react";

export default function App() {
  return (
    <DEXTUploadX5Provider
      authKey="jn+xziPdVh6f5KN17uFH... skip ...WiXAyO2FdI9r5XGfwxQ="
      productPath="/dx5/"
    >
      <UploadPage />
    </DEXTUploadX5Provider>
  );
}

You can hard-code authKey and productPath in the client code, or fetch them from a server API. In production, managing the auth key on the server is generally more common.

# Example of providing settings from an Express server
import express from "express";

const router = express.Router();

router.get("/api/dx5-config", (req, res) => {
  res.json({
    authKey: process.env.DX5_AUTHKEY,
    productPath: process.env.DX5_PRODUCT_PATH || "/dx5/"
  });
});

export default router;

# Example of fetching configuration in React and applying Provider
import { useEffect, useState } from "react";
import { DEXTUploadX5Provider } from "dextuploadx5-react";

export default function App() {
  const [config, setConfig] = useState(null);

  useEffect(() => {
    fetch("/api/dx5-config")
      .then((res) => res.json())
      .then((data) => setConfig(data));
  }, []);

  if (!config) return null;

  return (
    <DEXTUploadX5Provider
      authKey={config.authKey}
      productPath={config.productPath || "/dx5/"}
    >
      <UploadPage />
    </DEXTUploadX5Provider>
  );
}

If productPath and the actual static file placement path do not match, the component will not be created correctly.

Create the list-type UI

To create a list-type upload UI, render DEXTUploadX5List. It is common to assign a display size and connect callbacks to detect creation completion and errors.

import { useState } from "react";
import { DX5, DEXTUploadX5List } from "dextuploadx5-react";

export default function UploadPage() {
  const [version, setVersion] = useState("");

  const handleCreated = (id) => {
    const dx = DX5.get(id);
    setVersion(dx.getVersion());
  };

  const handleError = (id, code, msg) => {
    alert(id + " => " + code + "\n" + msg);
  };

  return (
    <div>
      <DEXTUploadX5List
        id="dext5"
        style={{ width: "100%", height: "320px" }}
        onCreated={handleCreated}
        onError={handleError}
      />
      <p>DEXTUploadX5 Version: {version}</p>
    </div>
  );
}

After the component is created, you can obtain the object with DX5.get("dext5") and connect actions such as file selection, upload, and list control. This document, however, only covers creating the UI on the screen.

Verify execution

The X5 list-type UI is created on the React screen when all of the following conditions are met.

The browser can load the X5 resources from the productPath path correctly.
A valid auth key is delivered.
DEXTUploadX5Provider is placed above DEXTUploadX5List.
API communication between the client and server is not blocked.

If the X5 list area appears on the screen and version information is confirmed in the onCreated callback, the basic initialization in the React environment is complete.

Next steps

Up to this point, the work is limited to creating the X5 component in a React screen. To handle actual file uploads and downloads, you still need to configure the server-side processing URL, response format, storage path, and error handling rules.

For upload configuration, refer to the React > Upload document.
For download configuration, refer to the React > Download document.