@phygrid/signals-react

A React library for integrating Phygrid Signals into your react applications.

Installation

Use either yarn or npm to install the package:

# Using yarn
yarn install @phygrid/signals-react

# Using npm
npm install @phygrid/signals-react

Usage

Basic Integration

The simplest way to integrate Signals into your React application is using the useGridSignals hook:

import React, { useEffect } from 'react';
import './App.css';
import { useGridSignals } from "@phygrid/signals-react";

function App() {
  const { isReady, signalsService } = useGridSignals();
  
  useEffect(() => {
    if (isReady) {
      // Example of sending an event
      signalsService.sendEvent(...);
    }
  }, [isReady, signalsService]);

  return (
    <div className="App">
      <p>Hello Signals</p>
    </div>
  );
}

export default App;

Custom Parameters

For more control, you can initialize the signals service with custom parameters using the useGridSignalsWithExternalParams hook:

import React, { useEffect } from 'react';
import './App.css';
import { useGridSignalsWithExternalParams } from "@phygrid/signals-react";

function App() {
  const initParams = {
    "deviceId": "device-12345",
    "installationId": "install-67890",
    "spaceId": "space-abcdef",
    "tenantId": "tenant-xyz",
    "appVersion": "1.0.0",
    "appId": "com.example.app",
    "environment": "production",
    "dataResidency": "EU",
    "country": "SE",
    "installationVersion": "2.3.4",
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR...",
    "clientUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
    "ip": "192.168.1.100"
  };
  
  const { isReady, signalsService } = useGridSignalsWithExternalParams(initParams);
  
  useEffect(() => {
    if (isReady) {
      // Example of sending an event
      signalsService.sendEvent(...);
    }
  }, [isReady, signalsService]);

  return (
    <div className="App">
      <p>Hello Signals</p>
    </div>
  );
}

export default App;

API Reference

Hooks

useGridSignals()

Initializes the signals service with default parameters.

Returns:

• isReady (boolean): Indicates whether the signals service is initialized and ready to use
• signalsService (object): The signals service instance for sending events

useGridSignalsWithExternalParams(initParams)

Initializes the signals service with custom parameters.

Parameters:

• initParams (object): Configuration object with the following properties:
  • deviceId (string): Unique identifier for the device
  • installationId (string): Unique identifier for the installation
  • spaceId (string): Identifier for the space
  • tenantId (string): Identifier for the tenant
  • appVersion (string): Version of the application
  • appId (string): Identifier for the application
  • environment (string): Environment (e.g., "production", "development")
  • dataResidency (string): Location for data residency
  • country (string): Country code
  • installationVersion (string): Version of the installation
  • accessToken (string): JWT or other access token
  • clientUserAgent (string): User agent string
  • ip (string): IP address

Returns:

• isReady (boolean): Indicates whether the signals service is initialized and ready to use
• signalsService (object): The signals service instance for sending events

Available Methods

Complete details regarding the available methods in signalsService can be found in here

---

Troubleshooting

If you find any errors when importing the package, make sure that

1. config-overrides.js is setup properly, an example is given below:

const webpack = require('webpack');
const path = require('path');

module.exports = function override(config, env) {
  config.module.rules.push({
    test: /\.(ts|tsx)$/,
    loader: 'ts-loader',
    options: {
      transpileOnly: true,
      compilerOptions: {
        module: 'esnext',
        moduleResolution: 'node',
      },
    },
    exclude: /node_modules/,
  });

  delete config.externals;

  config.plugins.push(
    new webpack.IgnorePlugin({ resourceRegExp: /^https-proxy-agent$/ }),
    new webpack.IgnorePlugin({ resourceRegExp: /^http-proxy-agent$/ })
  );

  config.resolve.fallback = {
    assert: require.resolve('assert/'),
    buffer: require.resolve('buffer/'),
    stream: require.resolve('stream-browserify'),
    util: require.resolve('util/'),
    net: false,
    tls: false,
    fs: false,
    child_process: false,
    http: false,
    https: false,
    os: false,
    url: false,
  };

  config.module.rules.push({
    test: /abort-controller/,
    resolve: { fullySpecified: false },
  });

  config.resolve.alias = {
    ...config.resolve.alias,
    'react': path.resolve('./node_modules/react'),
    'react-dom': path.resolve('./node_modules/react-dom')
  };

  return config;
};

2. Make sure that your webpack.config.js is setup properly, for example:

const webpack = require('webpack');
const path = require('path');

module.exports = function override(config, env) {
  // Add React resolution alias
  config.resolve.alias = {
    ...config.resolve.alias,
    'react': path.resolve('./node_modules/react'),
    'react-dom': path.resolve('./node_modules/react-dom')
  };

  // Add externals configuration
  config.externals = {
    ...config.externals,
    react: 'React',
    'react-dom': 'ReactDOM'
  };

  // Existing fallbacks for node.js core modules
  config.resolve.fallback = {
    http: require.resolve('stream-http'),
    https: require.resolve('https-browserify'),
    stream: require.resolve('stream-browserify'),
    util: require.resolve('util/'),
    os: require.resolve('os-browserify/browser'),
    assert: require.resolve('assert/'),
    net: false,
    tls: false,
  };
  
  config.plugins.push(
    new webpack.ProvidePlugin({
      process: 'process/browser',
      Buffer: ['buffer', 'Buffer'],
    })
  );
  
  return config;
};

3. If you are using typescript, make sure you have tsconfig.json setup properly, for example:

{
  "compilerOptions": {
    "target": "es5",
    "lib": [
      "dom",
      "dom.iterable",
      "esnext"
    ],
    "allowJs": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react",
    "baseUrl": "src"
  },
  "include": [
    "src"
  ]
}

4. For react version related issues, make sure you add following in your package.json file:

{
  "resolutions": {
      "react": "^18.0.0",
      "react-dom": "^18.0.0"
    },
}