Napi-rs Template Project (eslint-barrel-file-utils)

0.0.15 verified Thu Apr 23 auth: no javascript maintenance

The `eslint-barrel-file-utils` package serves as an example project built with `napi-rs`, a framework for constructing high-performance Node.js native addons using Rust. Currently at version 0.0.15, this package demonstrates the setup, build, testing, and release workflow for `napi-rs` projects rather than providing standalone ESLint utilities. Its release cadence is infrequent, aligning with updates to the underlying `napi-rs` template. A primary differentiator of `napi-rs` (and thus this template) is its robust, ABI-compatible native module generation across various operating systems (Windows, macOS, Linux, Android, FreeBSD) and Node.js versions (10, 14, 16, 18). It employs a unique distribution strategy where platform-specific binaries are published as separate `npm` packages and loaded via `optionalDependencies`, eliminating the need for users to install complex build toolchains like `node-gyp` for most use cases.

Common errors

error Error: Cannot find module 'eslint-barrel-file-utils/darwin-x64' or similar platform-specific module. ↓

cause The native binary for the current platform/architecture could not be found or loaded by Node.js.

fix

Ensure npm install (or yarn install) completed successfully. This error often indicates a problem during installation where the correct platform-specific optional dependency failed to download, or the native binary was not built for the target environment. Check npm logs for details or try cleaning node_modules and reinstalling. If developing, ensure yarn build was run to generate the local native addon.

error N-API Error: This function must be called on the main thread. ↓

cause A native function that interacts with the V8 JavaScript engine (e.g., creating objects or manipulating the JS event loop) was called from a Rust thread that is not the main Node.js event loop thread.

fix

For Rust functions intended to be called asynchronously and not block the main thread, ensure they use ThreadsafeFunction or Async patterns provided by napi-rs to safely communicate results back to the main JavaScript thread. Avoid direct V8 API calls from background threads.

error TypeError: 'argument' must be a number ↓

cause A JavaScript argument passed to a Rust function did not match the expected type (e.g., passing a string where a number was expected).

fix

Verify the JavaScript types of arguments passed to native functions match the Rust function signatures (e.g., i32 expects a number, String expects a string). Refer to the generated TypeScript type definitions for the correct function signatures.

Warnings

gotcha The package name `eslint-barrel-file-utils` is misleading. This package is primarily a template project for `napi-rs` native addons and does not contain any actual ESLint utility functions. Users seeking ESLint barrel file utilities should look for `eslint-plugin-barrel-files` (from the same author) or similar plugins. ↓

fix If intending to develop a `napi-rs` project, follow the template instructions (fork, rename). If seeking an ESLint plugin, install `eslint-plugin-barrel-files` instead.

breaking `napi-rs` v3 (released after `napi-rs` v2) introduced significant breaking changes in its CLI, configuration, and Rust API. Projects forked from this template that attempt to upgrade their `napi-rs` dependency to v3 will require code and configuration updates. Key changes include `napi.name` to `napi.binaryName`, `napi.triples` to `napi.targets`, and changes to `ThreadsafeFunction` usage. ↓

fix Consult the `napi-rs` v2 to v3 migration guide for detailed instructions on updating `Cargo.toml`, `package.json` configuration, and Rust code.

gotcha While `napi-rs` simplifies native addon development, local development and custom builds still require a Rust toolchain (`rustup`) to be installed. Prebuilt binaries distributed via `optionalDependencies` on npm typically mitigate this for end-users, but developers modifying the Rust source will need a functional Rust environment. ↓

fix Install the latest stable Rust toolchain via `rustup` as per the official Rust documentation. Ensure Node.js 10+ is also installed.

gotcha When passing `Buffer` or `TypedArray` instances between JavaScript and Rust, `napi-rs` v2 (which this template likely uses as `eslint-barrel-file-utils` is version 0.0.15) might introduce unnecessary overhead by automatically creating references. `napi-rs` v3 addresses this by enforcing explicit `Reference<Buffer>` or `BufferRef` for async scenarios, but v2 projects might incur performance costs or encounter unsoundness if `&mut _` is used with async functions. ↓

fix For optimal performance and correctness in `napi-rs` v2 projects, carefully manage `Buffer` and `TypedArray` ownership. Consider upgrading to `napi-rs` v3 and adopting its explicit `Reference<Buffer>` patterns for async operations to ensure zero-overhead data transfer and memory safety.

Install

npm install eslint-barrel-file-utils

yarn add eslint-barrel-file-utils

pnpm add eslint-barrel-file-utils

Imports

syncFunction
wrong
```
const { syncFunction } = require('eslint-barrel-file-utils');
```
correct
```
import { syncFunction } from 'eslint-barrel-file-utils';
```
ES Modules syntax is preferred; CommonJS `require` can be problematic with native addons and TypeScript types.

sleepFunction

wrong

const sleepFunction = require('eslint-barrel-file-utils').sleepFunction;

correct

import { sleepFunction } from 'eslint-barrel-file-utils';

Named exports are used for functions exposed from the native addon.

NativeAddonModule
wrong
```
import NativeAddonModule from 'eslint-barrel-file-utils';
```
correct
```
import * as NativeAddonModule from 'eslint-barrel-file-utils';
```
There is no default export; the native module exports multiple named functions. Use `* as` for grouping.

Quickstart

Demonstrates how to import and call both synchronous and asynchronous functions exposed by the N-API native addon.

import { syncFunction, sleepFunction } from 'eslint-barrel-file-utils';

console.log('Calling synchronous native function...');
const result = syncFunction();
console.log(`Sync function returned: ${result}`);

console.log('Calling asynchronous native function (sleep for 200ms)...');
// In a real application, you might `await` this, but for demonstration, we just call it.
sleepFunction(200);
console.log('Sleep function called. Execution continues in JS thread.');

// Await a promise if the sleepFunction were to return one
// async function runAsync() {
//   console.log('Calling truly async native function...');
//   const asyncResult = await sleepFunctionAsync(200);
//   console.log(`Async function completed after: ${asyncResult}ms`);
// }
// runAsync();