Reagraph's font import strategy for displaying non-Latin characters (such as Russian) in Vite apps

In the Vite project, when using Reagraph to draw graphics and try to display Russian and other non-Latin characters on nodes, the characters often cannot be displayed normally due to a failure to load the font file. The core solution is to declare font module types such as `.ttf` in the `vite-env.d.ts` file so that Vite can correctly parse and import these assets, thereby providing the necessary font support for Reagraph or other text rendering libraries.

Problem background and core challenges

When using React applications with the Reagraph library for data visualization, developers may encounter a common problem: when node labels contain non-Latin characters (such as Russian), these characters do not display correctly. Although you try to import font files directly through Reagraph's labelFontUrl property, or use a more advanced text rendering library such as troika-three-text, you may still encounter import errors or character display abnormalities. This is usually not a problem with the rendering logic of Reagraph or troika-three-text itself, but is caused by the module parsing mechanism of specific types of resources (such as .ttf font files) in the Vite build tool environment.

In order to optimize the development experience and build performance, Vite only recognizes some common module types by default. For non-JavaScript/TypeScript files such as .ttf, .png, .svg, etc., if they are not processed through Vite's built-in asset processing rules (for example, referenced as import.meta.url), or do not have an explicit type declaration, Vite may report an error in the TypeScript environment, preventing them from being imported and used correctly.

Solution: Declare the module type

The key to solving this problem is to explicitly tell the TypeScript compiler and Vite in the TypeScript declaration file (vite-env.d.ts) of the Vite project that the .ttf file should be treated as an importable module type. This way, when you try to import or reference a .ttf file in a component, Vite will correctly recognize it as an asset and handle it accordingly (for example, generating an accessible URL).

Implementation steps

1. Locate or create the vite-env.d.ts file: In the root directory of the Vite project, there is usually a file named vite-env.d.ts. If it doesn't exist, create one manually. This file is the environment declaration file provided by Vite for TypeScript projects.

2. Add module declaration: Open the vite-env.d.ts file and add the following declaration:

    /// <reference types="vite/client"></reference>
   
   declare module '*.png'
   declare module '*.svg'
   declare module '*.ttf'
   // If you need to support other font formats, such as .woff, .woff2, you can also declare them // declare module '*.woff'
   // declare module '*.woff2'

   • /// : This line is a reference to the Vite client type declaration, ensuring that Vite-related type hints work properly.
   • declare module '*.ttf': This line is the core. It tells the TypeScript compiler that any files ending in .ttf should be treated as a module, allowing you to introduce them through import statements in your code.

3. Restart the development server: After completing the above modifications, be sure to stop and restart the Vite development server (e.g., run npm run dev or yarn dev). This is to allow Vite to reload configuration and type declarations to ensure changes take effect.

Subsequent font references

After declaring the .ttf module in vite-env.d.ts, you can import the font file in the React component just like any other resource, passing its path to Reagraph's labelFontUrl property or troika-three-text's font configuration.

Sample code (used in Reagraph):

Suppose you have a Russian font file named NotoSans-Regular.ttf placed in the src/assets/fonts/ directory.

1. Import font files:

    // src/App.tsx or your component file import NotoSansFont from './assets/fonts/NotoSans-Regular.ttf';

   Once imported, the NotoSansFont variable will contain the URL path to the font file.

2. Configure Reagraph:

    import React from 'react';
   import { GraphCanvas } from 'reagraph';
   import NotoSansFont from './assets/fonts/NotoSans-Regular.ttf'; // Make sure the path is correct const nodes = [
     { id: 'node-1', label: 'Привет мир' }, // Russian: Hello World
     { id: 'node-2', label: 'Тестовый узел' },
   ];
   
   const edges = [
     { id: 'edge-1', source: 'node-1', target: 'node-2', label: 'connection' },
   ];
   
   function MyGraphComponent() {
     return (
       <div style="{{" height: width:>
         <graphcanvas nodes="{nodes}" edges="{edges}" layouttype="force" pass the imported font url to labelfonturl you can also adjust size and color labelfontcolor="#333" labelfontsize="{12}"></graphcanvas>
       </div>
     );
   }
   
   export default MyGraphComponent;

   With labelFontUrl={NotoSansFont}, Reagraph will be able to correctly load and use that font file to render Russian characters in node labels.

Things to note

• Font file path: Make sure the import path of the font file is correct. Vite processes these paths and converts them into accessible URLs at build time.
• The font file itself: Make sure the .ttf font file you use actually contains the required Russian or other non-Latin character set. Some fonts may only support Latin characters.
• Browser cache: Sometimes after modifying font files or configurations, browsers may cache old resources. If the changes don't take effect immediately, try clearing your browser cache or using incognito mode.
• Font loading time: External font files take time to load. You may see the default font until the font is fully loaded. Reagraph usually handles this situation, but in some cases you may want to consider waiting until the fonts are loaded before rendering the chart.
• Font Licensing: When using any third-party font, be sure to check its licensing agreement to make sure your use complies.

Summarize

In the Vite project, the core of dealing with the non-Latin character display problem on the Reagraph node is to solve Vite's module parsing of font files such as .ttf. By adding a simple declare module '*.ttf' declaration in vite-env.d.ts, you can make Vite recognize and import these assets correctly. Once the font files can be processed correctly by Vite, libraries such as Reagraph or troika-three-text can successfully load and apply these fonts to achieve correct rendering of multi-language characters. This method is not only applicable to font files, but also to other resource types that Vite does not recognize by default. It is an important skill in Vite project development.

The above is the detailed content of Reagraph's font import strategy for displaying non-Latin characters (such as Russian) in Vite apps. For more information, please follow other related articles on the PHP Chinese website!