{"id":10605,"library":"calendarize","title":"calendarize","description":"calendarize is a minimalist (202B) JavaScript utility designed to generate structured calendar views for a given month. Currently at version 1.1.1, it provides an array of arrays representing weeks, where each inner array contains 7 numbers corresponding to days of the month, with `0` indicating days outside the current month. The library is highly flexible, providing no date labels or internationalization (i18n) directly, which allows developers complete control over localization and rendering. It ships as ES Module, CommonJS, and UMD, making it suitable for various environments. Its main differentiator is its tiny footprint and unopinionated output, focusing solely on the grid structure rather than presentation, and it has a steady, albeit slow, release cadence driven by community contributions for minor enhancements.","status":"active","version":"1.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/lukeed/calendarize","tags":["javascript","calendar","utils","date","typescript"],"install":[{"cmd":"npm install calendarize","lang":"bash","label":"npm"},{"cmd":"yarn add calendarize","lang":"bash","label":"yarn"},{"cmd":"pnpm add calendarize","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This is a default export. For TypeScript, the type of `calendarize` is inferred or can be explicitly imported if needed.","wrong":"import { calendarize } from 'calendarize';","symbol":"calendarize","correct":"import calendarize from 'calendarize';"},{"note":"CommonJS usage for Node.js environments.","symbol":"calendarize","correct":"const calendarize = require('calendarize');"}],"quickstart":{"code":"import calendarize from 'calendarize';\n\n// Example 1: Calendar view for a specific date instance\n// Week = [Sun, Mon, Tue, Wed, Thu, Fri, Sat]\nconst dateInstanceView = calendarize(new Date('2024-07-20'));\nconsole.log('July 2024 (Sunday start):', dateInstanceView);\n/*\nOutput:\n[\n  [ 0,  1,  2,  3,  4,  5,  6],\n  [ 7,  8,  9, 10, 11, 12, 13],\n  [14, 15, 16, 17, 18, 19, 20],\n  [21, 22, 23, 24, 25, 26, 27],\n  [28, 29, 30, 31,  0,  0,  0]\n]\n*/\n\n// Example 2: Calendar view for a date string with Monday as the start of the week\n// Week = [Mon, Tue, Wed, Thu, Fri, Sat, Sun]\nconst mondayStartView = calendarize('Aug 01, 2024', 1);\nconsole.log('August 2024 (Monday start):', mondayStartView);\n/*\nOutput:\n[\n  [ 0,  0,  0,  1,  2,  3,  4],\n  [ 5,  6,  7,  8,  9, 10, 11],\n  [12, 13, 14, 15, 16, 17, 18],\n  [19, 20, 21, 22, 23, 24, 25],\n  [26, 27, 28, 29, 30, 31,  0]\n]\n*/","lang":"javascript","description":"Demonstrates generating a calendar view for a given date, including how to specify a different start day for the week using the `offset` parameter."},"warnings":[{"fix":"Always pass a `Date` object initialized with the desired timezone, e.g., `new Date('YYYY-MM-DDTHH:MM:SSZ')` or use robust date parsing libraries (like `date-fns` or `luxon`) to create a `Date` object before passing it to `calendarize`.","message":"When passing `string` or `number` values for the `date` parameter, Node.js may apply an incorrect timezone during conversion to a `Date` object, leading to unexpected calendar views (e.g., month off by a day).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"When iterating through the `Week` arrays, add a conditional check for `day === 0` to render an empty cell or specific placeholder (e.g., `''` or `null`) instead of attempting to process `0` as a valid date number.","message":"The output array contains `0` values for days that fall outside the current month's view. Developers must explicitly handle these `0`s when rendering the calendar, for instance, by displaying empty cells or styling them differently.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Integrate with an i18n library or manually create arrays for day labels (`['Sun', 'Mon', ...]`) and month names, mapping them to the `calendarize` output based on the `offset` parameter and locale expectations.","message":"The library explicitly does not provide day-of-week labels (e.g., 'Sun', 'Mon') or internationalization (i18n) support. This design choice requires developers to implement their own labeling and localization logic.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your project's `calendarize` dependency is at version `1.1.0` or higher to utilize the `offset` parameter. Update your `package.json` to specify `\"calendarize\": \">=1.1.0\"` or run `npm install calendarize@latest`.","message":"The `offset` parameter, which controls the starting day of the week, was introduced in version `1.1.0`. Using it in versions prior to `1.1.0` will result in an error or the parameter being ignored, as it was not part of the API.","severity":"breaking","affected_versions":"<1.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"To prevent timezone-related errors, always provide a `Date` object with explicit timezone control (e.g., `new Date('YYYY-MM-DDT00:00:00Z')`). For the week start, verify the `offset` value: `0` for Sunday (default), `1` for Monday, etc., to match your desired calendar layout. Ensure `calendarize` is `v1.1.0` or higher to use `offset`.","cause":"This often occurs due to Node.js timezone issues when parsing date strings, or misunderstanding how the `offset` parameter (which defines the starting day of the week) influences the output.","error":"Calendar view shows incorrect days for the month, or the first day of the week is not what I expected."},{"fix":"When iterating through the `Week` arrays, add a conditional check: `if (day === 0) { /* render empty */ } else { /* render day */ }`. This prevents processing `0` as a real date and allows for correct visual representation of empty cells.","cause":"The `calendarize` output uses `0` to represent days that fall outside the current month's view. Directly rendering or attempting to format `0` as a valid date without a check will lead to unexpected display or errors.","error":"When rendering, some days appear as '0' or cause 'Cannot read properties of undefined' when attempting to format them."}],"ecosystem":"npm"}