0
# Strip JSON Comments
1

2
Strip JSON Comments is a JavaScript utility library that removes single-line (`//`) and multi-line (`/* */`) comments from JSON strings while preserving original character positions for accurate error reporting. It enables the use of comments in JSON files, which is particularly useful for configuration files and development environments.
3

4
## Package Information
5

6
- **Package Name**: strip-json-comments
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript (ESM only, requires Node.js 14.16+)
9
- **Installation**: `npm install strip-json-comments`
10

11
## Core Imports
12

13
```javascript
14
import stripJsonComments from "strip-json-comments";
15
```
16

17
**Note**: This package is ESM-only and cannot be imported with `require()`. Use `import` syntax or dynamic imports.
18

19
## Basic Usage
20

21
```javascript
22
import stripJsonComments from "strip-json-comments";
23

24
const json = `{
25
	// Rainbows
26
	"unicorn": /* ❤ */ "cake"
27
}`;
28

29
const cleanJson = stripJsonComments(json);
30
JSON.parse(cleanJson);
31
//=> {unicorn: 'cake'}
32
```
33

34
## Capabilities
35

36
### Strip JSON Comments
37

38
Removes comments from JSON strings while maintaining original character positions for accurate error reporting.
39

40
```javascript { .api }
41
/**
42
 * Strip comments from JSON. Lets you use comments in your JSON files!
43
 * @param jsonString - JSON string that may contain comments
44
 * @param options - Configuration options
45
 * @returns JSON string without comments
46
 */
47
function stripJsonComments(jsonString: string, options?: Options): string;
48
```
49

50
**Parameters:**
51

52
- `jsonString` (string, required): JSON string that may contain single-line (`//`) or multi-line (`/* */`) comments
53
- `options` (object, optional): Configuration options for comment stripping behavior
54

55
**Returns:** `string` - JSON string with comments removed according to the specified options
56

57
**Throws:** `TypeError` if `jsonString` parameter is not a string
58

59
**Usage Examples:**
60

61
```javascript
62
// Basic comment stripping (default whitespace replacement)
63
const jsonWithComments = `{
64
	// This is a comment
65
	"name": "example",
66
	/* Multi-line
67
	   comment here */
68
	"value": 42
69
}`;
70

71
const cleaned = stripJsonComments(jsonWithComments);
72
// Comments are replaced with equivalent whitespace
73

74
// Remove comments entirely (no whitespace replacement)
75
const minimal = stripJsonComments(jsonWithComments, { whitespace: false });
76

77
// Strip trailing commas in addition to comments
78
const jsonWithTrailing = `{
79
	"name": "example",
80
	"value": 42,
81
}`;
82
const noTrailing = stripJsonComments(jsonWithTrailing, { trailingCommas: true });
83
```
84

85
## Types
86

87
```javascript { .api }
88
interface Options {
89
	/**
90
	 * Strip trailing commas in addition to comments.
91
	 * @default false
92
	 */
93
	readonly trailingCommas?: boolean;
94

95
	/**
96
	 * Replace comments and trailing commas with whitespace instead of stripping them entirely.
97
	 * @default true
98
	 */
99
	readonly whitespace?: boolean;
100
}
101
```
102

103
### Options Interface
104

105
Configuration object for customizing comment stripping behavior.
106

107
**Properties:**
108

109
- `trailingCommas` (boolean, optional): When `true`, removes trailing commas from objects and arrays in addition to comments. Default: `false`
110
- `whitespace` (boolean, optional): When `true`, replaces comments with equivalent whitespace to preserve character positions. When `false`, removes comments entirely. Default: `true`
111

112
## Key Features
113

114
### Position Preservation
115

116
By default, comments are replaced with whitespace rather than removed entirely. This ensures that:
117
- JSON parsing error line/column numbers remain accurate
118
- Original source mapping is preserved
119
- Debugging maintains correct position references
120

121
### Comment Types Supported
122

123
- **Single-line comments**: `// comment text`
124
- **Multi-line comments**: `/* comment text */`
125
- **Nested comment patterns**: Handles complex cases like `//` within `/* */` blocks
126

127
### String Handling
128

129
Comments inside JSON strings are preserved and not stripped:
130

131
```javascript
132
const jsonString = '{"url": "https://example.com//path"}';
133
stripJsonComments(jsonString); // Comments in strings are NOT removed
134
```
135

136
### Trailing Comma Support
137

138
Optional removal of trailing commas from JSON objects and arrays:
139

140
```javascript
141
const json = `{
142
	"name": "example",
143
	"items": [1, 2, 3,],
144
}`;
145

146
stripJsonComments(json, { trailingCommas: true });
147
// Removes trailing commas while handling comments
148
```
149

150
### Error Handling
151

152
- Validates input type and throws `TypeError` for non-string inputs
153
- Handles malformed or incomplete comment blocks gracefully
154
- Manages edge cases like escaped quotes and complex string patterns
155

156
### Line Ending Support
157

158
Properly handles different line ending formats:
159
- Unix (`\n`)
160
- Windows (`\r\n`)
161
- Mixed line endings within the same document