From 20dae3fbc01c0e726ebd29b3fce32deb480373ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?B=C3=A1rbara=20Celi?= <112641072+barbara-celi@users.noreply.github.com> Date: Fri, 27 Jun 2025 10:29:33 -0300 Subject: [PATCH 1/3] Create implementation.md --- docs/localization/implementation.md | 115 ++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 docs/localization/implementation.md diff --git a/docs/localization/implementation.md b/docs/localization/implementation.md new file mode 100644 index 0000000000..3e75bda66b --- /dev/null +++ b/docs/localization/implementation.md @@ -0,0 +1,115 @@ +--- +title: "Implementing FastStore Analyzer" +--- + +In this guide, you will learn how to securely implement [Extension points](LINK) in [FastStore modules](LINK) by using FastStore Analyzer. + +The FastStore Analyzer is a static analysis tool that helps maintain code quality and security in FastStore projects. By integrating it into your development workflow with customizable CLI hooks, it scans your codebase to identify issues before they affect your build. + +Follow the steps below to implement FastStore Analyzer in your store. + +## Before you begin + + + +### Install the FastStore Platform CLI + +Make sure you’re using the FastStore Platform CLI by installing the `@vtex/fsp-cli` package, which provides the necessary hooks and the basic structure for implementing the modules. + +Learn more in the [FastStore Platform CLI](LINK) guide. + +### Add the Analyzer to your project + +To add the Analyzer to your project, run the following command: + +```bash +pnpm add @vtex/fsp-analyzer +``` + +This will equip your project with the tools to maintain code quality and security standards throughout development. + +### Understand the `hooks` folder + +Your project's `hooks` folder allows you to add custom hooks to the development lifecycle. These hooks can be executed at different runtime stages, such as: + +- `preBuild`: Runs before the build process. +- `postBuild`: Runs after the build process. +- `preDev`: Runs before the development server starts. +- `postDev`: Runs after the development server starts. + +>ℹ Hooks are defined in the `src/hooks` folder and are executed according to the file name (Example: `pre.ts` will run before `post.ts`). + + + +## Instructions + +To ensure that the Analyzer runs as part of your build process and catches potential issues as early as possible, we recommend configuring the Analyzer in the `preBuild` hook. This hook allows the Analyzer to scan your code before the build starts, helping to detect and address issues early in the development cycle. + +### Step 1 - Creating a pre-build hook + +1. Open your FastStore project using the code editor of your choice. +2. Go to the `hooks/pre.tsx` file. +3. Add the following content: + + ```typescript + import { FastStoreSandboxAnalyzer } from "@vtex/fsp-analyzer"; + + export async function preBuild() { + const analyzer = new FastStoreSandboxAnalyzer(); + + try { + await analyzer.analyzeFiles({ + filePattern: '{{your-module}}/**/*.{js,ts,jsx,tsx,css,less,scss}', + cssOptions: { + allowedNamespaces: ['extension-'], + transformNonCompliant: true, + defaultNamespace: 'extension-', + verbose: true, + overwriteTransformed: true, + } + }); + } catch (error) { + console.error("Pre-build static analysis failed:", error); + throw error; + } + } + ``` + + | Field | Type | Description | + |:------|:-----|:------------| + | `filePattern` | `string` | Glob pattern defining the files to be analyzed (example: `.{js,ts,jsx,tsx,css,less,scss}`). **Replace `{{your-module}}` according to your scenario.** | + | `cssOptions` | `object` | Options for validating and transforming CSS namespace usage. | + |   ├─`allowedNamespaces` | `string` | Array of allowed CSS namespace prefixes (example: `['extension-']`). Only selectors with these prefixes will be considered compliant. | + |   ├─`transformNonCompliant` | `boolean` | If `true`, automatically updates non-compliant CSS selectors to match the expected namespace format. | + |   ├─`defaultNamespace` | `string` | Default namespace prefix to selectors when auto-fixing non-compliant CSS (example: ` 'extension-'`. | + |   ├─`verbose` | `boolean` | If `true`, provides detailed output and saves transformed files to disk. | + |   └─`overwriteTransformed` | `boolean` | If `true`, overwrites existing files with their transformed versions. | + +Learn more about CSS options in the [CSS Analysis](LINK) guide. + +### Step 2 - Executing static analysis + +Register the hook in your project's entry point: + +```typescript +export const hooks = { + preBuild, + // ... other hooks +}; +``` + +Run your project: + +```bash +pnpm run dev +``` + +Build your project: + +```bash +pnpm run build +``` + +Once you finish these steps, you should see the Analyzer output in the console as shown in the example below: + +![analyzer-output]() From 4d2a2acf7aa47d1bab11d0efc042bd88db51357f Mon Sep 17 00:00:00 2001 From: kaio-donadelli Date: Fri, 18 Jul 2025 16:36:57 -0300 Subject: [PATCH 2/3] Doc reviewed by localization. --- docs/localization/implementation.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/localization/implementation.md b/docs/localization/implementation.md index 3e75bda66b..1bfb1ceae9 100644 --- a/docs/localization/implementation.md +++ b/docs/localization/implementation.md @@ -2,9 +2,9 @@ title: "Implementing FastStore Analyzer" --- -In this guide, you will learn how to securely implement [Extension points](LINK) in [FastStore modules](LINK) by using FastStore Analyzer. +In this guide, you'll learn how to securely implement [Extension points](LINK) in [FastStore modules](LINK) by using FastStore Analyzer. -The FastStore Analyzer is a static analysis tool that helps maintain code quality and security in FastStore projects. By integrating it into your development workflow with customizable CLI hooks, it scans your codebase to identify issues before they affect your build. +FastStore Analyzer is a static analysis tool that helps maintain code quality and security in FastStore projects. By integrating it into your development workflow with customizable CLI hooks, it scans your codebase to identify issues before they affect your build. Follow the steps below to implement FastStore Analyzer in your store. @@ -28,7 +28,7 @@ pnpm add @vtex/fsp-analyzer This will equip your project with the tools to maintain code quality and security standards throughout development. -### Understand the `hooks` folder +### Explore the `hooks` folder Your project's `hooks` folder allows you to add custom hooks to the development lifecycle. These hooks can be executed at different runtime stages, such as: @@ -37,13 +37,13 @@ Your project's `hooks` folder allows you to add custom hooks to the development - `preDev`: Runs before the development server starts. - `postDev`: Runs after the development server starts. ->ℹ Hooks are defined in the `src/hooks` folder and are executed according to the file name (Example: `pre.ts` will run before `post.ts`). +>ℹ Hooks are defined in the `src/hooks` folder and are executed according to the file name (example: `pre.ts` will run before `post.ts`). ## Instructions -To ensure that the Analyzer runs as part of your build process and catches potential issues as early as possible, we recommend configuring the Analyzer in the `preBuild` hook. This hook allows the Analyzer to scan your code before the build starts, helping to detect and address issues early in the development cycle. +To ensure the Analyzer runs as part of your build process and catches potential issues as early as possible, we recommend configuring the Analyzer in the `preBuild` hook. This hook allows the Analyzer to scan your code before the build starts, helping to detect and address issues early in the development cycle. ### Step 1 - Creating a pre-build hook @@ -77,11 +77,11 @@ To ensure that the Analyzer runs as part of your build process and catches poten | Field | Type | Description | |:------|:-----|:------------| - | `filePattern` | `string` | Glob pattern defining the files to be analyzed (example: `.{js,ts,jsx,tsx,css,less,scss}`). **Replace `{{your-module}}` according to your scenario.** | + | `filePattern` | `string` | Glob pattern defining the files to be analyzed (example: `.{js,ts,jsx,tsx,css,less,scss}`). **Replace `{{your-module}}` based on your scenario.** | | `cssOptions` | `object` | Options for validating and transforming CSS namespace usage. | |   ├─`allowedNamespaces` | `string` | Array of allowed CSS namespace prefixes (example: `['extension-']`). Only selectors with these prefixes will be considered compliant. | |   ├─`transformNonCompliant` | `boolean` | If `true`, automatically updates non-compliant CSS selectors to match the expected namespace format. | - |   ├─`defaultNamespace` | `string` | Default namespace prefix to selectors when auto-fixing non-compliant CSS (example: ` 'extension-'`. | + |   ├─`defaultNamespace` | `string` | Default namespace prefix applied to selectors when auto-fixing non-compliant CSS (example: ` 'extension-'`. | |   ├─`verbose` | `boolean` | If `true`, provides detailed output and saves transformed files to disk. | |   └─`overwriteTransformed` | `boolean` | If `true`, overwrites existing files with their transformed versions. | @@ -110,6 +110,6 @@ Build your project: pnpm run build ``` -Once you finish these steps, you should see the Analyzer output in the console as shown in the example below: +After completing these steps, you should see the Analyzer output in the console, as shown in the example below: ![analyzer-output]() From c5dd6cddb22ff432d1079c8940a85f40c74ca68d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?B=C3=A1rbara=20Celi?= <112641072+barbara-celi@users.noreply.github.com> Date: Thu, 31 Jul 2025 16:59:40 -0300 Subject: [PATCH 3/3] chore/moving file to correct folder --- .../docs/faststore-analyzer}/implementation.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{localization => faststore/docs/faststore-analyzer}/implementation.md (100%) diff --git a/docs/localization/implementation.md b/docs/faststore/docs/faststore-analyzer/implementation.md similarity index 100% rename from docs/localization/implementation.md rename to docs/faststore/docs/faststore-analyzer/implementation.md