reactapp-version-sync

This package allows a React app to check for its version by fetching and inspecting the index.html file from its own remote location. It is useful when you want your app to dynamically detect its version or perform version-based actions, like cache busting, updates, or analytics.

Installation You can install the package via npm or Yarn:

npm install react-remote-version-checker

or

yarn add react-remote-version-checker

Usage

1. Basic Usage To use the react-remote-version-checker, you need to import and call the checkVersion function in your React app.

Example

import { checkVersion } from 'react-app-version-checker';

// Check for version key in the remote index.html
checkVersion(remoteLocation);

2. How It Works Fetching the index.html: The package fetches the index.html from the provided remote location. Extracting the Version Key: The index.html is parsed, and the package looks for a version key in the meta tags or a custom tag of your choice. Returning the Version: If the version is found, it returns the version number; otherwise, it throws an error. API checkVersion(remoteUrl: string, versionKeySelector: string = 'meta[name="version"]'): Promise Parameters: remoteUrl: The remote URL (including the domain) where the index.html can be found. versionKeySelector: A selector string to find the version in index.html (defaults to meta[name="version"]). Returns: A promise that resolves to the version string if found, or rejects if the version key is not found or the fetch fails.

Example with Custom Selector

If your version key is not in a meta tag with name="version" and instead is placed somewhere else (for example in a data-version attribute), you can customize the selector:

checkVersion({versionTag: 'meta', attribute: 'data-commit-hash', onVersionDiff: (withError) => console.log("Version Diff")})
  .catch(err => {
    console.error('Failed to retrieve version:', err);
  });

const options = {
  tagForHash: T,
  onVersionDiff: (failedCheck?: boolean) => void = () =>
    window.location.reload(),
  id: string | undefined = undefined,
  attribute: string = 'data-hash'
}

Error Handling

If the version key is not found or there is an issue with the network request, the promise will reject with an error message. You should handle errors gracefully, for example, with a catch block:

checkVersion('https://yourdomain.com/')
  .then((version) => {
    console.log('Version:', version);
  })
  .catch((err) => {
    console.error('Failed to fetch version:', err);
  });

Use Cases

The main goal of the library to is to provide the core logic to check the difference between cached and remote version of a react app. The first issue this is supposed to solve is forcing users with deprecated logic out of your website.

import React, { useEffect, useState } from 'react';
import { use } from 'react-remote-version-checker';

const App = () => {
  const { isLoggedIn, logout } = useAuthService(null);
  const { checkVersion, checking } = useVersionFetcher;

  useEffect(() => {
    if (isLoggedIn)
      checkVersion({
        versionTag: 'meta',
        attribute: 'data-commit-hash',
        onVersionDiff: (withError) => {
          window.alert('Could not check your website version');
          setTimout(() => logout(), 3000);
        },
      });
  }, [isLoggedIn]);

  if (checking) return <div>Loading</div>;

  if (error) {
    return <div>Error: {error}</div>;
  }

  return (
    <div>
      <h1>App Version: {version ? version : 'Loading version...'}</h1>
    </div>
  );
};

export default App;

Contributing

If you would like to contribute to this package, feel free to fork the repository and submit a pull request. Here are some ways you can contribute:

Report bugs or request features. Submit pull requests with fixes or improvements. Improve the documentation. License MIT License. See the LICENSE file for details.

Acknowledgments This package relies on the browser's fetch API to fetch the index.html from the provided URL. Parsing and extracting the version from index.html uses standard DOM methods available in modern browsers.