Skip to content

Commit dcf4185

Browse files
knowledgecodeknowledgecode
committed
Add installation and quick start guide
- Add detailed installation guide with package manager options - Include import methods for ES modules and CommonJS - Add quick start guide with common usage patterns - Include examples for locales, timezones, and date arithmetic
1 parent 2b9bc16 commit dcf4185

3 files changed

Lines changed: 503 additions & 0 deletions

File tree

‎docs/guide/index.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Introduction
2+
3+
**date-and-time** is the simplest, most intuitive date and time library for JavaScript and TypeScript. Built from the ground up with modern development practices, it provides a comprehensive set of tools for date manipulation, formatting, parsing, and timezone handling.
4+
5+
## Why date-and-time?
6+
7+
### 🚀 Modern & Performant
8+
9+
- Written entirely in **TypeScript** with ES2021 target
10+
- **Tree-shakable** modules for optimal bundle size
11+
- **Zero dependencies** for core functionality
12+
- Full **ES Modules** and **CommonJS** support
13+
14+
### 🌍 Internationalization Ready
15+
16+
- Support for **40+ locales** with native month/day names
17+
- Multiple **calendar systems** (Gregorian, Buddhist)
18+
- **Numeral systems** (Latin, Arabic, Bengali, Myanmar)
19+
- **Timezone-aware** formatting and parsing
20+
21+
### 🎯 Developer Experience
22+
23+
- **Full TypeScript** support with comprehensive type definitions
24+
- **IntelliSense** support in modern editors
25+
- **Consistent API** design across all functions
26+
- **Extensive documentation** and examples
27+
28+
### 📦 Production Ready
29+
30+
- **Node.js 18+** support
31+
- **Modern browser** compatibility (Chrome 85+, Firefox 78+, Safari 14+)
32+
- **Comprehensive test suite** with high coverage
33+
- **Battle-tested** in production environments
34+
35+
## Key Features
36+
37+
### Formatting and Parsing
38+
39+
- **`format()`** - Convert Date objects to formatted strings
40+
- **`parse()`** - Parse date strings into Date objects
41+
- **`compile()`** - Precompile format strings for performance
42+
- **`preparse()`** - Parse date strings and return intermediate results
43+
- **`isValid()`** - Validate date string formats
44+
- **`transform()`** - Transform date strings between different formats
45+
46+
### Date Arithmetic
47+
48+
- **`addYears()`, `addMonths()`, `addDays()`** - Date addition
49+
- **`addHours()`, `addMinutes()`, `addSeconds()`, `addMilliseconds()`** - Time addition
50+
- **`subtract()`** - Calculate time differences with Duration objects
51+
52+
### Utility Functions
53+
54+
- **`isLeapYear()`** - Check if a year is a leap year
55+
- **`isSameDay()`** - Check if two dates are on the same day
56+
57+
### Advanced Features
58+
59+
- **Timezone Support** - Comprehensive timezone data from timezonedb
60+
- **Locale Support** - 40+ languages with native formatting
61+
- **Plugin System** - Extensible with microsecond/nanosecond precision
62+
- **Duration Objects** - Rich time difference calculations
63+
64+
## Version 4.x Highlights
65+
66+
Version 4.x represents a complete rewrite with significant improvements:
67+
68+
### 🔄 Breaking Changes
69+
70+
- **TypeScript-first** development approach
71+
- **Integrated plugins** - timezone and timespan functionality built-in
72+
- **New API signatures** - options objects replace boolean parameters
73+
- **Modern JavaScript** - ES2021 features throughout
74+
75+
### 📈 Performance Improvements
76+
77+
- **Reduced bundle size** with tree-shaking
78+
79+
### 🛠 Developer Improvements
80+
81+
- **Expanded language support** - Now supporting 40+ locales
82+
- **Improved TypeScript** inference and completion
83+
- **Comprehensive documentation** with live examples
84+
85+
## Architecture
86+
87+
```typescript
88+
import { format, parse } from 'date-and-time';
89+
import ja from 'date-and-time/locales/ja';
90+
import Tokyo from 'date-and-time/timezones/Asia/Tokyo';
91+
92+
// Core functionality
93+
const date = new Date();
94+
const formatted = format(date, 'YYYY/MM/DD');
95+
96+
// Localized formatting
97+
const localized = format(date, 'YYYY年M月D日', { locale: ja });
98+
99+
// Timezone-aware operations
100+
const tokyoTime = format(date, 'YYYY-MM-DD HH:mm:ss', { timeZone: Tokyo });
101+
```
102+
103+
## Browser and Environment Support
104+
105+
### Node.js
106+
107+
- **Node.js 18.0.0+** (LTS recommended)
108+
- Full ES Modules support
109+
- CommonJS compatibility
110+
111+
### Browsers
112+
113+
| Browser | Minimum Version |
114+
|---------|----------------|
115+
| Chrome | 85+ |
116+
| Firefox | 78+ |
117+
| Safari | 14+ |
118+
| Edge | 85+ |
119+
120+
### Module Systems
121+
122+
- **ES Modules** (`.mjs`, `type: "module"`)
123+
- **CommonJS** (`.cjs`, traditional Node.js)
124+
- **TypeScript** (4.5+)
125+
- **Bundlers** (Webpack, Rollup, Vite, etc.)
126+
127+
## Getting Started
128+
129+
Ready to start using date-and-time? Continue to the [Installation Guide](./installation) to set up the library in your project.

‎docs/guide/installation.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
# Installation
2+
3+
Get started with date-and-time in your project using your preferred package manager.
4+
5+
## Package Manager Installation
6+
7+
::: code-group
8+
9+
```bash [npm]
10+
npm install date-and-time
11+
```
12+
13+
```bash [yarn]
14+
yarn add date-and-time
15+
```
16+
17+
```bash [pnpm]
18+
pnpm add date-and-time
19+
```
20+
21+
:::
22+
23+
## Requirements
24+
25+
### Runtime Requirements
26+
27+
- **Node.js**: Version 18.0.0 or higher
28+
- **Browsers**: ES2021 support required
29+
30+
### Development Requirements (optional)
31+
32+
- **TypeScript**: Version 4.5 or higher for full type support
33+
- **Modern bundler**: For optimal tree-shaking (Webpack 5+, Rollup, Vite, etc.)
34+
35+
## Import Methods
36+
37+
date-and-time supports both ES Modules and CommonJS, allowing you to use the import style that best fits your project.
38+
39+
### ES Modules (Recommended)
40+
41+
```typescript
42+
import { format, parse } from 'date-and-time';
43+
44+
format(new Date(), 'YYYY/MM/DD');
45+
// => 2025/08/23
46+
```
47+
48+
### CommonJS
49+
50+
```typescript
51+
const { format, parse } = require('date-and-time');
52+
53+
format(new Date(), 'YYYY/MM/DD');
54+
// => 2025/08/23
55+
```
56+
57+
## Importing Locales and Timezones
58+
59+
Locales and timezones are distributed as separate modules to support tree shaking:
60+
61+
### Locale Imports
62+
63+
```typescript
64+
// Import specific locales
65+
import ja from 'date-and-time/locales/ja';
66+
import es from 'date-and-time/locales/es';
67+
import fr from 'date-and-time/locales/fr';
68+
69+
// Use in formatting
70+
format(new Date(), 'YYYY年M月D日', { locale: ja });
71+
format(new Date(), 'D [de] MMMM [de] YYYY', { locale: es });
72+
format(new Date(), 'D MMMM YYYY', { locale: fr });
73+
```
74+
75+
For a complete list of all supported locales with import examples, see [Supported Locales](../locales).
76+
77+
### Timezone Imports
78+
79+
```typescript
80+
// Import specific timezones
81+
import Tokyo from 'date-and-time/timezones/Asia/Tokyo';
82+
import New_York from 'date-and-time/timezones/America/New_York';
83+
import London from 'date-and-time/timezones/Europe/London';
84+
85+
// Use in operations
86+
format(new Date(), 'YYYY-MM-DD HH:mm:ss', { timeZone: Tokyo });
87+
format(new Date(), 'YYYY-MM-DD HH:mm:ss', { timeZone: New_York });
88+
```
89+
90+
For a complete list of all supported timezones with import examples, see [Supported Timezones](../timezones).
91+
92+
### Numeral Systems
93+
94+
```typescript
95+
// Import numeral systems
96+
import arab from 'date-and-time/numerals/arab';
97+
import beng from 'date-and-time/numerals/beng';
98+
99+
format(new Date(), 'DD/MM/YYYY', { numeral: arab });
100+
// => ٠٨/٠٧/٢٠٢٥
101+
```
102+
103+
## Plugin Imports
104+
105+
Some advanced features are available as plugins:
106+
107+
```typescript
108+
import { format } from 'date-and-time';
109+
// Import specific plugins
110+
import microsecond from 'date-and-time/plugins/microsecond';
111+
import ordinal from 'date-and-time/plugins/ordinal';
112+
import zonename from 'date-and-time/plugins/zonename';
113+
114+
// Use plugin-specific tokens with plugins specified in options
115+
format(new Date(), 'MMMM DDD, YYYY', { plugins: [ordinal] }); // with ordinal plugin
116+
format(new Date(), 'HH:mm:ss.SSSSSS', { plugins: [microsecond] }); // with microsecond plugin
117+
```
118+
119+
## CDN Usage
120+
121+
For browser-only projects, you can use date-and-time directly from a CDN:
122+
123+
### ES Modules via CDN
124+
125+
```html
126+
<script type="module">
127+
import { format } from 'https://cdn.skypack.dev/date-and-time';
128+
129+
console.log(format(new Date(), 'YYYY/MM/DD'));
130+
</script>
131+
```
132+
133+
### Via unpkg
134+
135+
```html
136+
<script type="module">
137+
import { format } from 'https://unpkg.com/date-and-time@4/dist/index.js';
138+
139+
console.log(format(new Date(), 'YYYY/MM/DD'));
140+
</script>
141+
```
142+
143+
## Bundle Size
144+
145+
::: tip Tree Shaking Benefits
146+
date-and-time is built with tree-shaking in mind. You only bundle the functions and locales you actually use, resulting in optimal bundle sizes. Modern bundlers like Webpack 5, Rollup, and Vite automatically eliminate unused code, ensuring your application stays lightweight.
147+
:::
148+
149+
## Verification
150+
151+
After installation, verify that the library works correctly:
152+
153+
```typescript
154+
import { format } from 'date-and-time';
155+
156+
console.log(format(new Date(), 'YYYY/MM/DD HH:mm:ss'));
157+
// Should output current date in YYYY/MM/DD HH:mm:ss format
158+
```
159+
160+
## Next Steps
161+
162+
Now that you have date-and-time installed, you can:
163+
164+
1. **[Quick Start](./quick-start)** - Learn the basics with simple examples
165+
2. **[API Reference](/api/)** - Dive deep into all available functions
166+
167+
## Troubleshooting
168+
169+
### TypeScript Issues
170+
171+
If you encounter TypeScript errors, ensure you're using TypeScript 4.5+ and have the latest version of date-and-time:
172+
173+
```bash
174+
npm install typescript@latest date-and-time@latest
175+
```
176+
177+
### Module Resolution Issues
178+
179+
For Node.js projects using ES Modules, ensure your `package.json` includes:
180+
181+
```json
182+
{
183+
"type": "module"
184+
}
185+
```
186+
187+
For CommonJS projects, this field should be omitted or set to `"commonjs"`.

0 commit comments

Comments
 (0)