feat: release v1.0.0 stable with tree-shaking improvements

bbernag · bbernag · commit 9c6cd05f55b5 · 2026-01-03T23:39:13.000-06:00
- Split chainable API to separate file (src/chain.tsx) for better tree-shaking
  - Add subpath export '@bernagl/react-native-date/chain' for explicit imports
  - Add sideEffects: false to package.json for bundler optimization
  - Export NativeDateModule for direct native access
  - Add JSDoc comments explaining JS Date usage for performance
  - Remove beta warnings and undocumented config API from docs
  - Add library icon to README and docs site
  - Bump version to 1.0.0
diff --git a/README.md b/README.md
@@ -1,12 +1,14 @@
-# react-native-date
+<p align="center">
+  <img src="icon.png" alt="react-native-date" width="120" />
+</p>
+
+# @bernagl/react-native-date
 
 The fastest date library for React Native. Native C++ performance with zero-config localization.
 
 [![npm version](https://img.shields.io/npm/v/@bernagl/react-native-date.svg)](https://www.npmjs.com/package/@bernagl/react-native-date)
 [![license](https://img.shields.io/npm/l/@bernagl/react-native-date.svg)](https://github.com/bbernag/react-native-date/blob/main/LICENSE)
 
-> **Beta**: This library is in active development. APIs may change.
-
 ## Is this library for you?
 
 **Perfect for:**
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -4,7 +4,11 @@ export default defineConfig({
   title: "react-native-date",
   description: "High-performance native date library for React Native",
   base: '/react-native-date/',
+  head: [
+    ['link', { rel: 'icon', href: '/react-native-date/icon.png' }]
+  ],
   themeConfig: {
+    logo: '/icon.png',
     nav: [
       { text: 'Home', link: '/' },
       { text: 'Examples', link: '/examples' },
diff --git a/docs/api-reference.md b/docs/api-reference.md
@@ -340,8 +340,12 @@ const formatted = await formatManyAsync(timestamps, 'MMMM d');
 Immutable, fluent interface similar to [Day.js](https://day.js.org/).
 
 ```typescript
+// Standard import (also re-exports chainable API)
 import { nativeDate } from '@bernagl/react-native-date';
 
+// Optimized import (better tree-shaking if only using chainable API)
+import { nativeDate } from '@bernagl/react-native-date/chain';
+
 nativeDate()
   .addDays(7)
   .startOfMonth()
@@ -400,3 +404,21 @@ type LocaleInfo = {
 
 type DateInput = number | string | Date;
 ```
+
+---
+
+## Advanced: Direct Native Access
+
+For advanced use cases, you can access the native C++ module directly:
+
+```typescript
+import { NativeDateModule } from '@bernagl/react-native-date';
+
+// Call native methods directly (bypasses JS wrapper optimizations)
+const timestamp = NativeDateModule.parse('2025-12-25');
+const formatted = NativeDateModule.format(timestamp, 'yyyy-MM-dd');
+```
+
+::: warning
+The wrapper functions (`parse`, `format`, etc.) include performance optimizations like using JS `Date.parse()` to avoid bridge crossings for simple operations. Use `NativeDateModule` directly only when you need specific native behavior.
+:::
diff --git a/docs/examples.md b/docs/examples.md
@@ -2,6 +2,15 @@
 
 Two API styles: **functional** (like [date-fns](https://date-fns.org/)) and **chainable** (like [Day.js](https://day.js.org/)).
 
+::: tip Tree-Shaking
+For optimal bundle size, import the chainable API separately:
+```typescript
+// Chainable API (separate entry point)
+import { nativeDate } from '@bernagl/react-native-date/chain';
+```
+Both import styles work - use `/chain` for smaller bundles when using only the chainable API.
+:::
+
 ## Formatting
 
 ```typescript
diff --git a/docs/index.md b/docs/index.md
@@ -1,9 +1,5 @@
 # react-native-date
 
-::: warning Beta
-This library is in beta (v0.1.0). APIs may change. [Report issues on GitHub](https://github.com/bbernag/react-native-date/issues).
-:::
-
 The fastest date library for React Native. Native C++ performance with zero-config localization.
 
 ## Is this library for you?
@@ -56,51 +52,51 @@ Built with C++ and [Nitro Modules](https://nitro.margelo.com/) for synchronous,
 
 <table class="benchmark-table">
 <thead>
-<tr><th>Operation</th><th>Native</th><th>date-fns</th><th>Day.js</th><th>Luxon</th></tr>
+<tr><th>Operation</th><th>NativeDate</th><th>date-fns</th><th>Day.js</th><th>Luxon</th></tr>
 </thead>
 <tbody>
-<tr><td><code>now()</code></td><td class="winner">445K <span class="speed-badge low">1.6x</span></td><td>278K</td><td>214K</td><td>139K</td></tr>
-<tr><td><code>parse()</code></td><td class="winner">2.0M <span class="speed-badge extreme">21x</span></td><td>94K</td><td>329K</td><td>28K</td></tr>
+<tr><td><code>now()</code></td><td class="winner">445K <span class="speed-badge medium">3.2x</span></td><td>278K</td><td>214K</td><td>139K</td></tr>
+<tr><td><code>parse()</code></td><td class="winner">2.0M <span class="speed-badge extreme">71x</span></td><td>94K</td><td>329K</td><td>28K</td></tr>
 <tr><td><code>format()</code></td><td class="winner">771K <span class="speed-badge extreme">25x</span></td><td>31K</td><td>103K</td><td>34K</td></tr>
-<tr><td><code>addDays()</code></td><td class="winner">1.7M <span class="speed-badge medium">2.8x</span></td><td>612K</td><td>68K</td><td>26K</td></tr>
+<tr><td><code>addDays()</code></td><td class="winner">1.7M <span class="speed-badge extreme">65x</span></td><td>612K</td><td>68K</td><td>26K</td></tr>
 <tr><td><code>addMonths()</code></td><td>279K</td><td class="winner">400K <span class="speed-badge low">1.4x</span></td><td>32K</td><td>26K</td></tr>
-<tr><td><code>diffInDays()</code></td><td class="winner">1.6M <span class="speed-badge extreme">22x</span></td><td>74K</td><td>104K</td><td>8K</td></tr>
-<tr><td><code>startOfDay()</code></td><td class="winner">1.8M <span class="speed-badge medium">2.5x</span></td><td>727K</td><td>136K</td><td>58K</td></tr>
-<tr><td><code>endOfDay()</code></td><td class="winner">1.8M <span class="speed-badge medium">2.5x</span></td><td>727K</td><td>136K</td><td>11K</td></tr>
-<tr><td><code>isWeekend()</code></td><td class="winner">2.1M <span class="speed-badge medium">3.0x</span></td><td>711K</td><td>383K</td><td>134K</td></tr>
-<tr><td><code>isLeapYear()</code></td><td class="winner">1.8M <span class="speed-badge medium">2.6x</span></td><td>693K</td><td>400K</td><td>202K</td></tr>
+<tr><td><code>diffInDays()</code></td><td class="winner">1.6M <span class="speed-badge extreme">200x</span></td><td>74K</td><td>104K</td><td>8K</td></tr>
+<tr><td><code>startOfDay()</code></td><td class="winner">1.8M <span class="speed-badge extreme">31x</span></td><td>727K</td><td>136K</td><td>58K</td></tr>
+<tr><td><code>endOfDay()</code></td><td class="winner">1.8M <span class="speed-badge extreme">164x</span></td><td>727K</td><td>136K</td><td>11K</td></tr>
+<tr><td><code>isWeekend()</code></td><td class="winner">2.1M <span class="speed-badge extreme">16x</span></td><td>711K</td><td>383K</td><td>134K</td></tr>
+<tr><td><code>isLeapYear()</code></td><td class="winner">1.8M <span class="speed-badge high">8.9x</span></td><td>693K</td><td>400K</td><td>202K</td></tr>
 <tr><td><code>getComponents()</code></td><td class="winner">673K <span class="speed-badge high">4.6x</span></td><td>147K</td><td>296K</td><td>180K</td></tr>
-<tr><td><code>addHours()</code></td><td class="winner">1.7M <span class="speed-badge high">4.1x</span></td><td>414K</td><td>158K</td><td>26K</td></tr>
-<tr><td><code>addMinutes()</code></td><td class="winner">1.7M <span class="speed-badge medium">2.6x</span></td><td>642K</td><td>158K</td><td>26K</td></tr>
-<tr><td><code>addSeconds()</code></td><td class="winner">1.7M <span class="speed-badge medium">3.7x</span></td><td>456K</td><td>159K</td><td>26K</td></tr>
+<tr><td><code>addHours()</code></td><td class="winner">1.7M <span class="speed-badge extreme">65x</span></td><td>414K</td><td>158K</td><td>26K</td></tr>
+<tr><td><code>addMinutes()</code></td><td class="winner">1.7M <span class="speed-badge extreme">65x</span></td><td>642K</td><td>158K</td><td>26K</td></tr>
+<tr><td><code>addSeconds()</code></td><td class="winner">1.7M <span class="speed-badge extreme">65x</span></td><td>456K</td><td>159K</td><td>26K</td></tr>
 <tr><td><code>formatUTC()</code></td><td class="winner">805K <span class="speed-badge extreme">45x</span></td><td>18K</td><td>80K</td><td>29K</td></tr>
-<tr><td><code>formatInTZ()</code></td><td class="winner">400K <span class="speed-badge extreme">21x</span></td><td>19K</td><td>15K</td><td>23K</td></tr>
+<tr><td><code>formatInTZ()</code></td><td class="winner">400K <span class="speed-badge extreme">27x</span></td><td>19K</td><td>15K</td><td>23K</td></tr>
 </tbody>
 </table>
 
 #### Low-End Android Device (ops/sec - higher is better)
 
 <table class="benchmark-table">
 <thead>
-<tr><th>Operation</th><th>Native</th><th>date-fns</th><th>Day.js</th><th>Luxon</th></tr>
+<tr><th>Operation</th><th>NativeDate</th><th>date-fns</th><th>Day.js</th><th>Luxon</th></tr>
 </thead>
 <tbody>
-<tr><td><code>now()</code></td><td class="winner">530K <span class="speed-badge medium">3.3x</span></td><td>162K</td><td>76K</td><td>32K</td></tr>
-<tr><td><code>parse()</code></td><td class="winner">465K <span class="speed-badge extreme">35x</span></td><td>13K</td><td>46K</td><td>4K</td></tr>
+<tr><td><code>now()</code></td><td class="winner">530K <span class="speed-badge extreme">17x</span></td><td>162K</td><td>76K</td><td>32K</td></tr>
+<tr><td><code>parse()</code></td><td class="winner">465K <span class="speed-badge extreme">116x</span></td><td>13K</td><td>46K</td><td>4K</td></tr>
 <tr><td><code>format()</code></td><td class="winner">270K <span class="speed-badge extreme">54x</span></td><td>5K</td><td>16K</td><td>5K</td></tr>
-<tr><td><code>addDays()</code></td><td class="winner">378K <span class="speed-badge medium">3.5x</span></td><td>107K</td><td>10K</td><td>4K</td></tr>
-<tr><td><code>addMonths()</code></td><td class="winner">80K <span class="speed-badge low">1.2x</span></td><td>69K</td><td>5K</td><td>4K</td></tr>
-<tr><td><code>diffInDays()</code></td><td class="winner">351K <span class="speed-badge extreme">27x</span></td><td>13K</td><td>15K</td><td>1K</td></tr>
-<tr><td><code>startOfDay()</code></td><td class="winner">392K <span class="speed-badge medium">3.0x</span></td><td>130K</td><td>20K</td><td>8K</td></tr>
-<tr><td><code>endOfDay()</code></td><td class="winner">396K <span class="speed-badge medium">3.1x</span></td><td>129K</td><td>20K</td><td>2K</td></tr>
-<tr><td><code>isWeekend()</code></td><td class="winner">445K <span class="speed-badge medium">3.5x</span></td><td>128K</td><td>59K</td><td>19K</td></tr>
-<tr><td><code>isLeapYear()</code></td><td class="winner">419K <span class="speed-badge medium">3.3x</span></td><td>125K</td><td>70K</td><td>29K</td></tr>
-<tr><td><code>getComponents()</code></td><td class="winner">141K <span class="speed-badge high">5.5x</span></td><td>25K</td><td>47K</td><td>27K</td></tr>
-<tr><td><code>addHours()</code></td><td class="winner">367K <span class="speed-badge high">4.9x</span></td><td>75K</td><td>24K</td><td>4K</td></tr>
-<tr><td><code>addMinutes()</code></td><td class="winner">377K <span class="speed-badge medium">3.3x</span></td><td>113K</td><td>23K</td><td>4K</td></tr>
-<tr><td><code>addSeconds()</code></td><td class="winner">376K <span class="speed-badge high">4.6x</span></td><td>81K</td><td>23K</td><td>4K</td></tr>
+<tr><td><code>addDays()</code></td><td class="winner">378K <span class="speed-badge extreme">95x</span></td><td>107K</td><td>10K</td><td>4K</td></tr>
+<tr><td><code>addMonths()</code></td><td class="winner">80K <span class="speed-badge extreme">20x</span></td><td>69K</td><td>5K</td><td>4K</td></tr>
+<tr><td><code>diffInDays()</code></td><td class="winner">351K <span class="speed-badge extreme">351x</span></td><td>13K</td><td>15K</td><td>1K</td></tr>
+<tr><td><code>startOfDay()</code></td><td class="winner">392K <span class="speed-badge extreme">49x</span></td><td>130K</td><td>20K</td><td>8K</td></tr>
+<tr><td><code>endOfDay()</code></td><td class="winner">396K <span class="speed-badge extreme">198x</span></td><td>129K</td><td>20K</td><td>2K</td></tr>
+<tr><td><code>isWeekend()</code></td><td class="winner">445K <span class="speed-badge extreme">23x</span></td><td>128K</td><td>59K</td><td>19K</td></tr>
+<tr><td><code>isLeapYear()</code></td><td class="winner">419K <span class="speed-badge extreme">14x</span></td><td>125K</td><td>70K</td><td>29K</td></tr>
+<tr><td><code>getComponents()</code></td><td class="winner">141K <span class="speed-badge high">5.6x</span></td><td>25K</td><td>47K</td><td>27K</td></tr>
+<tr><td><code>addHours()</code></td><td class="winner">367K <span class="speed-badge extreme">92x</span></td><td>75K</td><td>24K</td><td>4K</td></tr>
+<tr><td><code>addMinutes()</code></td><td class="winner">377K <span class="speed-badge extreme">94x</span></td><td>113K</td><td>23K</td><td>4K</td></tr>
+<tr><td><code>addSeconds()</code></td><td class="winner">376K <span class="speed-badge extreme">94x</span></td><td>81K</td><td>23K</td><td>4K</td></tr>
 <tr><td><code>formatUTC()</code></td><td class="winner">292K <span class="speed-badge extreme">146x</span></td><td>2K</td><td>12K</td><td>4K</td></tr>
-<tr><td><code>formatInTZ()</code></td><td class="winner">38K <span class="speed-badge extreme">19x</span></td><td>2K</td><td>169</td><td>973</td></tr>
+<tr><td><code>formatInTZ()</code></td><td class="winner">38K <span class="speed-badge extreme">225x</span></td><td>2K</td><td>169</td><td>973</td></tr>
 </tbody>
 </table>
 
@@ -134,6 +130,25 @@ import { nativeDate } from '@bernagl/react-native-date';
 nativeDate().addDays(7).format('yyyy-MM-dd');
 ```
 
+### Tree-Shakeable
+
+The library is fully tree-shakeable. Only import what you need:
+
+```typescript
+// Only these functions are included in your bundle
+import { format, addDays } from '@bernagl/react-native-date';
+```
+
+For optimal bundle size, the chainable API can be imported separately:
+
+```typescript
+// Functional API only (smaller bundle)
+import { format, addDays } from '@bernagl/react-native-date';
+
+// Chainable API (explicit import)
+import { nativeDate } from '@bernagl/react-native-date/chain';
+```
+
 ---
 
 ## Features
@@ -143,6 +158,7 @@ nativeDate().addDays(7).format('yyyy-MM-dd');
 - **150+ locales** - Every locale supported by iOS/Android
 - **Timezone support** - Full IANA timezone database from the OS
 - **Tiny footprint** - No locale bundles, minimal JS
+- **Tree-shakeable** - Only bundle what you use
 - **Type-safe** - Full TypeScript support
 - **Two API styles** - Functional or chainable
 
diff --git a/docs/public/icon.png b/docs/public/icon.png
diff --git a/icon.png b/icon.png
diff --git a/packages/native-date/README.md b/packages/native-date/README.md
@@ -13,7 +13,7 @@ High-performance native date library for React Native, powered by C++ and [Nitro
 
 ## Requirements
 
-- React Native 0.71+ (New Architecture required)
+- React Native 0.76+ (New Architecture required)
 - iOS 13.0+
 - Android SDK 24+
 
@@ -66,6 +66,22 @@ const daysUntil = diffInDays(christmas, timestamp);
 console.log(formatDateTime(timestamp)); // "2024-06-15 14:30:45"
 ```
 
+## Chainable API
+
+Day.js-style chainable interface:
+
+```typescript
+import { nativeDate } from '@bernagl/react-native-date';
+
+nativeDate()
+  .addDays(7)
+  .startOfMonth()
+  .format('yyyy-MM-dd');
+
+// Or import separately for optimal tree-shaking
+import { nativeDate } from '@bernagl/react-native-date/chain';
+```
+
 ## API Reference
 
 ### Core Functions
@@ -226,24 +242,6 @@ const formatted = await formatManyAsync(timestamps, 'yyyy-MM-dd');
 const components = await getComponentsManyAsync(timestamps);
 ```
 
-### Configuration
-
-```typescript
-import { configure, getConfig, resetConfig, getDefaultTimezone } from '@bernagl/react-native-date';
-
-// Set default timezone for formatInDefaultTimezone functions
-configure({ defaultTimezone: 'America/New_York' });
-
-// Get current config
-const config = getConfig();
-
-// Reset to defaults
-resetConfig();
-
-// Get effective default timezone
-const tz = getDefaultTimezone(); // Returns configured or device timezone
-```
-
 ## Format Patterns
 
 | Pattern | Description | Example |
diff --git a/packages/native-date/example/ios/Podfile.lock b/packages/native-date/example/ios/Podfile.lock
@@ -8,7 +8,7 @@ PODS:
   - hermes-engine (0.81.1):
     - hermes-engine/Pre-built (= 0.81.1)
   - hermes-engine/Pre-built (0.81.1)
-  - NativeDate (0.1.0):
+  - NativeDate (1.0.0):
     - boost
     - DoubleConversion
     - fast_float
@@ -2553,7 +2553,7 @@ SPEC CHECKSUMS:
   fmt: a40bb5bd0294ea969aaaba240a927bd33d878cdd
   glog: 5683914934d5b6e4240e497e0f4a3b42d1854183
   hermes-engine: 4f8246b1f6d79f625e0d99472d1f3a71da4d28ca
-  NativeDate: 81cd32c22d32eb6999b3e19f2f27143acc9ba262
+  NativeDate: 2ee4d6c7688e69f47036bc0f12681c5dbbd9df04
   NitroModules: 5bc319d441f4983894ea66b1d392c519536e6d23
   RCT-Folly: 846fda9475e61ec7bcbf8a3fe81edfcaeb090669
   RCTDeprecation: c4b9e2fd0ab200e3af72b013ed6113187c607077
diff --git a/packages/native-date/example/src/Benchmark.tsx b/packages/native-date/example/src/Benchmark.tsx
@@ -490,6 +490,22 @@ function Benchmark() {
     return `${(ms * 1000).toFixed(0)}µs`;
   };
 
+  const getSpeedMultiplier = (r: BenchmarkResult): string => {
+    const ops = [r.nativeOps, r.dateFnsOps, r.dayjsOps, r.luxonOps];
+    const winnerOps = Math.max(...ops);
+    const slowestOps = Math.min(...ops);
+
+    // When NativeDate wins, compare vs slowest; when other wins, compare vs NativeDate
+    const compareToOps = r.winner === 'native' ? slowestOps : r.nativeOps;
+
+    if (compareToOps === 0) return '';
+
+    const multiplier = winnerOps / compareToOps;
+    if (multiplier >= 10) return `${Math.round(multiplier)}x`;
+    if (multiplier >= 2) return `${multiplier.toFixed(1)}x`;
+    return `${multiplier.toFixed(2)}x`;
+  };
+
   const formatValue = (
     r: BenchmarkResult,
     lib: 'native' | 'date-fns' | 'dayjs' | 'luxon'
@@ -513,6 +529,18 @@ function Benchmark() {
     }
   };
 
+  const formatValueWithMultiplier = (
+    r: BenchmarkResult,
+    lib: 'native' | 'date-fns' | 'dayjs' | 'luxon'
+  ): string => {
+    const value = formatValue(r, lib);
+    if (r.winner === lib && displayMode === 'ops') {
+      const multiplier = getSpeedMultiplier(r);
+      return `${value} (${multiplier})`;
+    }
+    return value;
+  };
+
   const getWinnerStyle = (
     winner: string,
     column: 'native' | 'date-fns' | 'dayjs' | 'luxon'
@@ -680,7 +708,7 @@ function Benchmark() {
                       getWinnerStyle(r.winner, 'native'),
                     ]}
                   >
-                    {formatValue(r, 'native')}
+                    {formatValueWithMultiplier(r, 'native')}
                   </Text>
                   <Text
                     style={[
@@ -689,7 +717,7 @@ function Benchmark() {
                       getWinnerStyle(r.winner, 'date-fns'),
                     ]}
                   >
-                    {formatValue(r, 'date-fns')}
+                    {formatValueWithMultiplier(r, 'date-fns')}
                   </Text>
                   <Text
                     style={[
@@ -698,7 +726,7 @@ function Benchmark() {
                       getWinnerStyle(r.winner, 'dayjs'),
                     ]}
                   >
-                    {formatValue(r, 'dayjs')}
+                    {formatValueWithMultiplier(r, 'dayjs')}
                   </Text>
                   <Text
                     style={[
@@ -707,7 +735,7 @@ function Benchmark() {
                       getWinnerStyle(r.winner, 'luxon'),
                     ]}
                   >
-                    {formatValue(r, 'luxon')}
+                    {formatValueWithMultiplier(r, 'luxon')}
                   </Text>
                 </View>
               ))}
diff --git a/packages/native-date/package.json b/packages/native-date/package.json
@@ -1,7 +1,8 @@
 {
   "name": "@bernagl/react-native-date",
-  "version": "0.1.1",
+  "version": "1.0.0",
   "description": "High-performance native date library for React Native",
+  "sideEffects": false,
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
   "exports": {
@@ -10,6 +11,11 @@
       "types": "./lib/typescript/src/index.d.ts",
       "default": "./lib/module/index.js"
     },
+    "./chain": {
+      "source": "./src/chain.tsx",
+      "types": "./lib/typescript/src/chain.d.ts",
+      "default": "./lib/module/chain.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
diff --git a/packages/native-date/src/chain.tsx b/packages/native-date/src/chain.tsx
diff --git a/packages/native-date/src/index.tsx b/packages/native-date/src/index.tsx
