@sherrylinks/slinks NPM

@sherrylinks/slinks

React components, hooks, adapters, and utilities for integrating SherryLinks MiniApps into web applications and browser extensions.

Overview

Slinks provides the tools to easily embed SherryLinks functionality. It allows you to:

Render MiniApps based on metadata using the MiniAppComponent.
Integrate with EVM wallets using Wagmi via the useWagmiAdapter.
Use a dedicated adapter (SherryExtensionAdapter) for browser extension environments.
Detect and process SherryLinks URLs found on web pages.
Observe platforms like Twitter/X to automatically enhance links with MiniApp previews or buttons (twitterObserverEVM).

Installation

npm install @sherrylinks/slinks @sherrylinks/slinks-core wagmi viem @tanstack/react-query react react-dom
# or
yarn add @sherrylinks/slinks @sherrylinks/slinks-core wagmi viem @tanstack/react-query react react-dom
# or
pnpm add @sherrylinks/slinks @sherrylinks/slinks-core wagmi viem @tanstack/react-query react react-dom

Note: @sherrylinks/slinks-core, react, react-dom, wagmi, viem, and @tanstack/react-query are peer dependencies.

Basic Usage (React App)

Import CSS: Import the necessary styles in your main application file.

// e.g., in src/main.tsx or src/App.tsx
import '@sherrylinks/slinks/index.css';

Set up Wagmi: Ensure your application is wrapped with WagmiProvider and QueryClientProvider.

Use the Adapter and Component:

import { MiniAppComponent, useWagmiAdapter } from '@sherrylinks/slinks';
import { createMetadata, ValidatedMetadata } from '@sherrylinks/sdk'; // Assuming SDK provides validation
import '@sherrylinks/slinks/index.css'; // Don't forget the CSS!

// Your MiniApp Metadata (fetch or define it)
const rawMetadata = { /* ... your metadata object ... */ };

function MyComponent() {
  const adapter = useWagmiAdapter(); // Hook to get wallet interaction functions

  // Validate metadata (example using a hypothetical SDK function)
  let validatedMetadata: ValidatedMetadata | undefined;
  try {
    validatedMetadata = createMetadata(rawMetadata);
  } catch (error) {
    console.error("Invalid Metadata:", error);
    // Handle invalid metadata case
  }

  if (!validatedMetadata) {
    return <div>Error loading MiniApp metadata.</div>;
  }

  return (
    <div>
      <h1>My App with Slinks</h1>
      <MiniAppComponent
        metadata={validatedMetadata}
        adapter={adapter}
        // securityState can be 'trusted', 'unknown', 'malicious' based on directory lookup
        securityState="trusted"
      />
    </div>
  );
}

export default MyComponent;

Key Features & Exports

Components:
- MiniAppComponent: Renders the main MiniApp UI based on metadata.
- WalletButton: A simple button component for wallet connection flows.
- SlinksPreview: (If exported) A component to show a preview based on a URL.
Hooks:
- useWagmiAdapter: Provides a SherryAdapter instance integrated with Wagmi for wallet interactions (connect, sign, send transaction, etc.).
Adapters:
- SherryAdapter: Interface defining the required wallet interaction methods.
- SherryExtensionAdapter: An adapter specifically designed for use within browser extensions, communicating via chrome.runtime.sendMessage.
Utilities:
- detectSherryUrl: Checks if a URL is potentially a SherryLink.
- fetchSlinksMetadata: Fetches metadata from a given URL.
- sanitizeText, processUrlWithAction: URL processing helpers.
Extension Integration:
- setupTwitterObserverEVM: Initializes an observer for Twitter/X to find and enhance links.
- handleNewNode: Function called by the observer when a potential link node is found.

Browser Environment & Polyfills

This library aims to work in modern browser environments, including browser extensions. It uses tsup for bundling and includes necessary polyfills (like Buffer) for browser compatibility. See CONTRIBUTING.md for more details on the build process and polyfill strategy if you encounter issues.