README
Table of contents
- Overview
- Installation
- API
- Interfaces
- ParserOptions
- PrettierOptions
- ResolvePrettierConfigOptions
- ResolverOptions
- MDXOptions
Overview
Parsing a source file will generate the following information:
- ESM: List of story named exports
- ESM: Default export stories file information
- MDX: List of
<Story />
story tags - MDX: List of Frontammetr or
<Meta />
stories file information - Source code extracted for the stories
- Source code of the entire stories file
- List of all attributes(ie parameters) passed to ESM/MDX stories
- List of story function arguments passed to ESM/MDX stories
- Usage location (in the source code) of the function arguments
- Extract 'component' information for stories: import clause, source file, source location
- Extract package.json repository information for the stories file
- Extract package.json repository information for the components file (when the components and the stories and in different packages)
Installation
This package is usually installed as part of the @component-controls package, but you can also install it standalone to parse story files and extract information in a script
$ npm install @component-controls/instrument --save-dev
API
Functions
Defined in core/instrument/src/index.ts
parseStories
▸ parseStories(source
: string, filePath
: string, options?
: InstrumentOptions): Promise‹Store›
Parse and instrument a javascript, typescript or MDX file of stories
Parameters:
Name | Type | Description |
---|---|---|
source |
string | Source of the file to be instrumented |
filePath |
string | Resolved file path name. |
options? |
InstrumentOptions | Instrumenting options |
Returns: Promise‹Store›
Default options
Defined in core/instrument/src/types.ts
ParserOptions
defaultParserOptions:• plugins: "typescript" | "jsx"[] = ['jsx', 'typescript']
• sourceType: "module" = "module"
ResolverOptions
defaultResolveOptions:• extensions: string[] = ['.js', '.jsx', '.ts', '.tsx', '.vue', '.mjs', '.es', '.es6']
ComponentOptions
defaultComponentOptions:• sourceFiles: boolean = true;
StoriesOptions
defaultStoriesOptions:• sourceFiles: boolean = false;
Interfaces
InstrumentOptions
Options that can control the parsing and instrumentation process
Defined in core/instrument/src/types.ts
Properties
• components? : ComponentOptions
Options for extracting stories information.
• stories? : StoriesOptions
Options for extracting component information.
• extractPropsFn? : PropsInfoExtractor
optional module to extract prop tables information for components
• parser? : ParserOptions
Options to control babel parser.
• prettier? : PrettierOptions | false
prettier options are used to prettify the code at the end of the process this is useful for "story" code, where the story is extracted from the full file passing a value of false as prettier option will disabled prettifying
• resolver? : ResolverOptions
Options to control resolving filenames.
InstrumentOptionsMDX
extends InstrumentOptions) and adds options for mdx-js
.
Properties
• mdx? : MDXOptions
Options for mdx-js compiling
ComponentOptions
Options for extracting component information.
Defined in core/instrument/src/types.ts
Properties
• resolveFile? : undefined | (componentName: string, filePath: string) => string | undefined;
Callback function to resolve the source file name of a component. Return false if this file should not be processed.
• sourceFiles? : boolean
If set to false, will not save the component's source file.
• package? : PackageInfoOptions | false
Otions for extracting repository information from the component's package,json file.
StoriesOptions
Options for extracting stories information.
Defined in core/instrument/src/types.ts
Properties
• sourceFiles? : boolean
If set to false, will not save the stories's source file, only the source of each individual story.
• package? : PackageInfoOptions | false
Options for extracting repository information from the component's package,json file.
ParserOptions
Options to control the @babel/parser
parsing process
Defined in /babel-parser/typings/babel-parser.d.ts
Properties
• allowAwaitOutsideFunction? : undefined | false | true
By default, await use is not allowed outside of an async function. Set this to true to accept such code.
• allowImportExportEverywhere? : undefined | false | true
By default, import and export declarations can only appear at a program's top level. Setting this option to true allows them anywhere where a statement is allowed.
• allowReturnOutsideFunction? : undefined | false | true
By default, a return statement at the top level raises an error. Set this to true to accept such code.
• allowSuperOutsideMethod? : undefined | false | true
• allowUndeclaredExports? : undefined | false | true
By default, exported identifiers must refer to a declared variable. Set this to true to allow export statements to reference undeclared variables.
• createParenthesizedExpressions? : undefined | false | true
By default, the parser adds information about parentheses by setting
extra.parenthesized
to true
as needed.
When this option is true
the parser creates ParenthesizedExpression
AST nodes instead of using the extra
property.
• plugins? : ParserPlugin[]
Array containing the plugins that you want to enable.
• ranges? : undefined | false | true
Adds a ranges property to each node: [node.start, node.end]
• sourceFilename? : undefined | string
Correlate output AST nodes with their source filename. Useful when generating code and source maps from the ASTs of multiple input files.
• sourceType? : "script" | "module" | "unambiguous"
Indicate the mode the code should be parsed in. Can be one of "script", "module", or "unambiguous". Defaults to "script". "unambiguous" will make @babel/parser attempt to guess, based on the presence of ES6 import or export statements. Files with ES6 imports and exports are considered "module" and are otherwise "script".
• startLine? : undefined | number
By default, the first line of code parsed is treated as line 1. You can provide a line number to alternatively start with. Useful for integration with other source tools.
• strictMode? : undefined | false | true
Should the parser work in strict mode. Defaults to true if sourceType === 'module'. Otherwise, false.
• tokens? : undefined | false | true
Adds all parsed tokens to a tokens property on the File node.
PrettierOptions
Options to control the prettier
code formatting process
Defined in @types/prettier/index.d.ts
Properties
• arrowParens? : "avoid" | "always"
Include parentheses around a sole arrow function parameter.
• bracketSpacing? : undefined | false | true
Print spaces between brackets in object literals.
• endOfLine? : "auto" | "lf" | "crlf" | "cr"
Which end of line characters to apply.
• filepath? : undefined | string
Specify the input filepath. This will be used to do parser inference.
• htmlWhitespaceSensitivity? : "css" | "strict" | "ignore"
How to handle whitespaces in HTML.
• insertPragma? : undefined | false | true
Prettier can insert a special @format marker at the top of files specifying that the file has been formatted with prettier. This works well when used in tandem with the --require-pragma option. If there is already a docblock at the top of the file then this option will add a newline to it with the @format marker.
• jsxBracketSameLine? : undefined | false | true
Put the >
of a multi-line JSX element at the end of the last line instead of being alone on the next line.
• jsxSingleQuote? : undefined | false | true
Use single quotes in JSX.
• parser? : BuiltInParserName | CustomParser
Specify which parser to use.
• plugins? : string | Plugin[]
The plugin API is in a beta state.
• printWidth?: number
Specify the line length that the printer will wrap on.
• proseWrap? : boolean | "always" | "never" | "preserve"
By default, Prettier will wrap markdown text as-is since some services use a linebreak-sensitive renderer. In some cases you may want to rely on editor/viewer soft wrapping instead, so this option allows you to opt out.
• quoteProps? : "as-needed" | "consistent" | "preserve"
Change when properties in objects are quoted.
• rangeEnd? : undefined | number
Format only a segment of a file.
• rangeStart? : undefined | number
Format only a segment of a file.
• requirePragma? : undefined | false | true
Prettier can restrict itself to only format files that contain a special comment, called a pragma, at the top of the file. This is very useful when gradually transitioning large, unformatted codebases to prettier.
• semi? : undefined | false | true
Print semicolons at the ends of statements.
• singleQuote? : undefined | false | true
Use single quotes instead of double quotes.
• tabWidth?: number
Specify the number of spaces per indentation-level.
• trailingComma? : "none" | "es5" | "all"
Print trailing commas wherever possible.
• useTabs?: boolean
Indent lines with tabs instead of spaces
• vueIndentScriptAndStyle? : undefined | false | true
Whether or not to indent the code inside