Registry / serialization / tzdata-northamerica

tzdata-northamerica

JSON →
library1.0.48jsnpmunverified

This package provides a machine-readable JSON representation of the 'northamerica' region from the official IANA Time Zone Database (TZDB). It is a pure data package, offering a static snapshot of time zone rules and historical offsets specific to North American regions, intended for consumption by time zone calculation libraries rather than performing computations itself. The current stable version, 1.0.48, reflects the IANA TZDB 2026a release. The package follows the IANA TZDB release cadence, typically updating several times a year to incorporate geopolitical changes to time zones (e.g., changes in DST rules, country-wide offset shifts). Its key differentiator among similar data packages is its focus on a specific geographical subset, leading to a smaller footprint for applications that only require North American time zone data, and its direct JSON format which is easy to parse.

npm install tzdata-northamerica
INSTALL
IMPORT
SIG · TZDATA-NORTHAMERIC
T
tzdata-northamerica
serializationjavascriptv1.0.48
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

jsonData
✓ import jsonData from 'tzdata-northamerica';
✗ const jsonData = require('tzdata-northamerica');
For Node.js, the package exports the JSON data object as its default export. While CommonJS `require` is shown in the README, ESM `import` is the modern approach and generally works for JSON modules or CJS modules that export a single object. Avoid `import { someProperty } from 'tzdata-northamerica'` as there are no named exports.
tzdataNorthamerica
✓ <!-- In HTML: <script src="./node_modules/tzdata-northamerica/tzdata-northamerica.js"></script> --> <script> function onLoad() { const data = tzdataNorthamerica; console.log('Loaded North America TZ data in browser.'); } </script>
For browser usage, including the UMD bundle script in your HTML creates a global variable `tzdataNorthamerica` which holds the time zone data.

This quickstart demonstrates how to import and access time zone data for North American zones in a Node.js environment. It shows how to retrieve the raw JSON data for specific zones like 'America/New_York' and 'America/Los_Angeles', and illustrates that non-North American zones will not be present in this package. It also hints at how this data would be integrated with a time zone calculation library.

import jsonData from 'tzdata-northamerica'; // Access specific time zone data by IANA name const newYorkData = jsonData['America/New_York']; const losAngelesData = jsonData['America/Los_Angeles']; console.log('--- Time Zone Data for America/New_York ---'); if (newYorkData) { // The data structure is an object where keys might represent years or rule sets. // This example just shows a simplified view of its content. console.log(`America/New_York data is available. It has ${Object.keys(newYorkData).length} top-level entries.`); const firstKey = Object.keys(newYorkData)[0]; if (firstKey) { console.log(`First entry for America/New_York (key: ${firstKey}):`, newYorkData[firstKey]); } } else { console.log('Error: America/New_York data not found. This should not happen with tzdata-northamerica.'); } console.log('\n--- Time Zone Data for America/Los_Angeles ---'); if (losAngelesData) { console.log(`America/Los_Angeles data is available. It has ${Object.keys(losAngelesData).length} top-level entries.`); } else { console.log('Error: America/Los_Angeles data not found. This should not happen with tzdata-northamerica.'); } // Attempting to access a non-North American zone will result in undefined const berlinData = jsonData['Europe/Berlin']; console.log('\nAttempting to access Europe/Berlin (not in this package):', berlinData); // Expected output for Berlin: undefined // To use this data meaningfully, typically you'd pass it to a library like timezonecomplete. // Example (conceptual, requires timezonecomplete setup): // import { TzDatabase, DateTime } from 'timezonecomplete'; // TzDatabase.init([jsonData]); // Initialize with the loaded data // const nowInNYC = new DateTime('now', 'America/New_York'); // console.log('Current time in New York (conceptual):', nowInNYC.toString());
Debug
Known issues
breakingThe underlying IANA TZ Database is updated frequently to reflect geopolitical changes (e.g., new DST rules, standard time zone offsets, changes in political boundaries affecting time). These data updates, while not code-breaking, can alter time calculations for past and future dates if your application relies on specific historical zone data. For example, `v1.0.40` (tzdata 2024a) included significant changes for Kazakhstan and Palestine.
fix
Always use the latest version of `tzdata-northamerica` to ensure the most accurate and up-to-date time zone information. Be aware that time zone calculations using previous versions of the data may yield different results. Regularly review IANA TZDB release notes for significant changes.
affects: >=1.0.0
gotchaThis package is a *subset* of the full IANA TZ database, containing only zones from the 'northamerica' file (e.g., America/New_York, Pacific/Honolulu). It does not contain time zone data for other continents or regions like Europe, Asia, or Africa.
fix
If your application requires global time zone data, you should install the main `tzdata` package or combine specific regional packages like `tzdata-europe`, `tzdata-asia`, etc., as needed. Do not assume `tzdata-northamerica` provides comprehensive global coverage.
affects: >=1.0.0
gotchaThis package provides raw time zone *data* (a JSON object) and does not include any logic or functions for performing time zone calculations (e.g., converting dates, determining offsets for a given timestamp, formatting).
fix
You must use this data in conjunction with a dedicated time zone library (e.g., `timezonecomplete`, `luxon`, `moment-timezone`) that can interpret the IANA TZDB format and perform date/time manipulations. This package is solely a data source for such libraries.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'America/New_York') or similar `TypeError` when accessing a zone
The module was not correctly imported or loaded, or you are trying to access a time zone that does not exist in the loaded data.
fix
Ensure `import jsonData from 'tzdata-northamerica';` or `const jsonData = require('tzdata-northamerica');` is correctly executed and that `jsonData` holds the expected object. Verify the time zone string (e.g., 'America/New_York') is spelled correctly and is part of the North American dataset.
tzdataNorthamerica is not defined
When used in a browser, the UMD script `tzdata-northamerica.js` was not loaded correctly or executed before your accessing script, or the path to the script was incorrect.
fix
Ensure the `<script src="./node_modules/tzdata-northamerica/tzdata-northamerica.js"></script>` tag is present in your HTML *before* the script that tries to access `tzdataNorthamerica`. Check the file path to ensure it points to the correct location of the UMD bundle.
Expected time zone 'Europe/Berlin' but got 'undefined' when accessing `jsonData['Europe/Berlin']`
You are attempting to retrieve data for a time zone that is not part of the North America-specific dataset provided by this package.
fix
This package only contains IANA zones from North America. If you need data for other regions, use the main `tzdata` package or other regional `tzdata-*` packages (e.g., `tzdata-europe`).
Upgrade
Version history
1.0.48latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
26 hits · last 30 days
node
22
Amazon
1
OpenAI (training)
1
Resources
tzdata-northamerica — npm install tzdata-northamerica · libregistry