strapi2front 0.4.0 → 0.4.2

package/README.md

@@ -1,10 +1,10 @@
 <div align="center">
-  <a href="https://strapi2front.dev">
+  <!-- <a href="https://strapi2front.dev">
     <picture>
       <source media="(prefers-color-scheme: dark)" srcset="https://strapi2front.dev/logo-dark.svg">
       <img alt="strapi2front logo" src="https://strapi2front.dev/logo-light.svg" height="128">
     </picture>
-  </a>
+  </a> -->
   <h1>strapi2front</h1>
 
 <a href="https://elevenestudio.com"><img alt="Made by Eleven Estudio" src="https://img.shields.io/badge/MADE%20BY%20Eleven%20Estudio-000000.svg?style=for-the-badge&labelColor=000"></a>
@@ -36,6 +36,7 @@ npx strapi2front sync
 ⊹ **Type Generation** - Auto-generate TypeScript interfaces from your Strapi schema\
 ⊹ **Service Generation** - Create typed service functions for all content types\
 ⊹ **Astro Actions** - Generate type-safe Astro Actions for client/server data fetching\
+⊹ **JSDoc Support** - Generate JavaScript files with JSDoc annotations (no TypeScript required)\
 ⊹ **Smart Detection** - Automatically detects framework, TypeScript, and package manager\
 ⊹ **Strapi v4 & v5** - Full support for both Strapi versions\
 ⊹ **By-Feature Structure** - Organize generated code by feature (screaming architecture)
@@ -65,16 +66,105 @@ src/strapi/
 
 - Node.js 18+
 - Strapi v4 or v5
-- Astro 4+ (more frameworks coming soon)
+- Astro 4+ (for Astro Actions, more frameworks coming soon)
 
-## Learn more
+---
+
+## Quick Setup
+
+### 1. Create a Strapi API Token
+
+You need an API token with **read-only access** to the Content-Type Builder:
+
+1. Go to **Strapi Admin** → **Settings** → **API Tokens**
+2. Create a new **Custom** token
+3. Enable these permissions:
+   - **Content-type-builder**: `getComponents`, `getComponent`, `getContentTypes`, `getContentType`
+   - **I18n** (optional): `listLocales`
+4. Add the token to your `.env`:
+
+```env
+STRAPI_TOKEN=your-token-here
+```
+
+> This token only reads schema structure, not your content data.
+
+### 2. Initialize
+
+```bash
+npx strapi2front@latest init
+```
+
+### 3. Sync Types
+
+```bash
+npx strapi2front sync
+```
+
+---
+
+## Configuration
+
+After init, a `strapi.config.ts` is created:
+
+```typescript
+import { defineConfig } from "strapi2front";
+
+export default defineConfig({
+  url: "http://localhost:1337",
+  strapiVersion: "v5",
+  apiPrefix: "/api",
+  output: {
+    path: "src/strapi",
+  },
+  features: {
+    types: true,
+    services: true,
+    actions: true,
+  },
+});
+```
+
+### Key Options
+
+| Option | Description |
+|--------|-------------|
+| `url` | Your Strapi instance URL |
+| `strapiVersion` | `"v4"` or `"v5"` |
+| `apiPrefix` | API prefix (default: `/api`) |
+| `outputFormat` | `"typescript"` or `"jsdoc"` |
+| `moduleType` | `"esm"` or `"commonjs"` (auto-detected) |
+| `output.path` | Where to generate files |
+| `output.structure` | `"by-feature"` or `"by-layer"` |
+
+### Environment Variables
+
+```env
+STRAPI_URL=http://localhost:1337
+STRAPI_TOKEN=your-api-token
+STRAPI_API_PREFIX=/api
+```
+
+---
+
+## Framework Support
+
+| Framework | Types | Services | Actions |
+|-----------|-------|----------|---------|
+| Astro 4+  | ✅    | ✅       | ✅      |
+| Next.js   | ✅    | ✅       | 🔜 Soon |
+| Nuxt      | ✅    | ✅       | 🔜 Soon |
+| Other     | ✅    | ✅       | ❌      |
+
+---
+
+## Full Documentation
 
-⊹ Visit [strapi2front.dev](https://strapi2front.dev) to learn more about the project.\
-⊹ Visit [strapi2front.dev/docs](https://strapi2front.dev/docs) to view the full documentation.
+For complete documentation including troubleshooting, advanced configuration, and examples, see the [main README](https://github.com/eleven-estudio/strapi2front#readme).
 
 ## Contributing
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md) for details.
 
 ## Security
 
@@ -84,7 +174,7 @@ Please report any issues to [hello@elevenestudio.com](mailto:hello@elevenestudio
 
 ## License
 
-MIT - see [LICENSE](LICENSE) for details.
+MIT - see [LICENSE](../../LICENSE) for details.
 
 ## Disclaimer
 

package/dist/bin/strapi2front.js

@@ -2,7 +2,7 @@
 import { Command } from 'commander';
 import pc4 from 'picocolors';
 import * as p from '@clack/prompts';
-import fs4 from 'fs/promises';
+import fs5 from 'fs/promises';
 import path6 from 'path';
 import { spawn, execSync } from 'child_process';
 import fs6 from 'fs';
@@ -26,7 +26,7 @@ var FRAMEWORK_DETECTORS = {
 async function detectFramework(cwd = process.cwd()) {
   const pkgPath = path6.join(cwd, "package.json");
   try {
-    const pkgContent = await fs4.readFile(pkgPath, "utf-8");
+    const pkgContent = await fs5.readFile(pkgPath, "utf-8");
     const pkg = JSON.parse(pkgContent);
     const deps = { ...pkg.dependencies, ...pkg.devDependencies };
     for (const [pkgName, detector] of Object.entries(FRAMEWORK_DETECTORS)) {
@@ -34,7 +34,7 @@ async function detectFramework(cwd = process.cwd()) {
         for (const configFile of detector.configFiles) {
           const configPath = path6.join(cwd, configFile);
           try {
-            await fs4.access(configPath);
+            await fs5.access(configPath);
             return {
               name: detector.name,
               version: deps[pkgName],
@@ -72,10 +72,10 @@ async function detectTypeScript(cwd = process.cwd()) {
   for (const configFile of TS_CONFIG_FILES) {
     const configPath = path6.join(cwd, configFile);
     try {
-      await fs4.access(configPath);
+      await fs5.access(configPath);
       const pkgPath = path6.join(cwd, "package.json");
       try {
-        const pkgContent = await fs4.readFile(pkgPath, "utf-8");
+        const pkgContent = await fs5.readFile(pkgPath, "utf-8");
         const pkg = JSON.parse(pkgContent);
         const deps = { ...pkg.dependencies, ...pkg.devDependencies };
         return {
@@ -109,7 +109,7 @@ async function detectPackageManager(cwd = process.cwd()) {
   for (const [lockFile, pm] of Object.entries(LOCK_FILES)) {
     const lockPath = path6.join(cwd, lockFile);
     try {
-      await fs4.access(lockPath);
+      await fs5.access(lockPath);
       return {
         name: pm,
         lockFile
@@ -140,6 +140,34 @@ function getInstallDevCommand(pm, pkg) {
   };
   return commands2[pm];
 }
+async function detectModuleType(cwd = process.cwd()) {
+  try {
+    const packageJsonPath = path6.join(cwd, "package.json");
+    const content = await fs5.readFile(packageJsonPath, "utf-8");
+    const packageJson = JSON.parse(content);
+    if (packageJson.type === "module") {
+      return { type: "esm", reason: 'package.json has "type": "module"' };
+    }
+    if (packageJson.type === "commonjs") {
+      return { type: "commonjs", reason: 'package.json has "type": "commonjs"' };
+    }
+  } catch {
+  }
+  const esmIndicators = [
+    "next.config.mjs",
+    "nuxt.config.mjs",
+    "vite.config.mjs",
+    "astro.config.mjs"
+  ];
+  for (const file of esmIndicators) {
+    try {
+      await fs5.access(path6.join(cwd, file));
+      return { type: "esm", reason: `Found ${file} (ESM config file)` };
+    } catch {
+    }
+  }
+  return { type: "commonjs", reason: "Default (no ESM indicators found)" };
+}
 function getMajorVersion(version) {
   if (!version) return null;
   const match = version.replace(/^[\^~]/, "").match(/^(\d+)/);
@@ -192,6 +220,19 @@ async function runInitPrompts(detection) {
     return null;
   }
   const strapiUrl = (strapiUrlInput || "").trim() || defaultUrl;
+  p.log.message(
+    pc4.dim(
+      `
+  To generate a token: Strapi Admin > Settings > API Tokens > Create new API Token
+  Required permissions:
+    Content-type-builder:
+      - Components: getComponents, getComponent
+      - Content-types: getContentTypes, getContentType
+    I18n (if using localization):
+      - Locales: listLocales
+`
+    )
+  );
   const strapiToken = await p.text({
     message: "What is your Strapi API token?",
     placeholder: "Press Enter to skip (you can add it later in .env)"
@@ -350,6 +391,11 @@ async function initCommand(_options) {
   }
   s.start("Creating configuration files...");
   try {
+    let moduleType = "commonjs";
+    if (answers.outputFormat === "jsdoc") {
+      const detected = await detectModuleType(cwd);
+      moduleType = detected.type;
+    }
     const configExtension = answers.outputFormat === "jsdoc" ? "js" : "ts";
     const configContent = generateConfigFile({
       strapiUrl: answers.strapiUrl,
@@ -358,17 +404,18 @@ async function initCommand(_options) {
       outputFormat: answers.outputFormat,
       outputDir: answers.outputDir,
       generateActions: answers.generateActions,
-      generateServices: answers.generateServices
+      generateServices: answers.generateServices,
+      moduleType
     });
     const configPath = path6.join(cwd, `strapi.config.${configExtension}`);
-    await fs4.writeFile(configPath, configContent, "utf-8");
+    await fs5.writeFile(configPath, configContent, "utf-8");
     const envPath = path6.join(cwd, ".env");
     await appendToEnvFile(envPath, {
       STRAPI_URL: answers.strapiUrl,
       STRAPI_TOKEN: answers.strapiToken
     });
     const outputPath = path6.join(cwd, answers.outputDir);
-    await fs4.mkdir(outputPath, { recursive: true });
+    await fs5.mkdir(outputPath, { recursive: true });
     s.stop("Configuration files created");
     const installDeps = await p.confirm({
       message: "Install required dependencies (strapi2front, strapi-sdk-js)?",
@@ -428,6 +475,7 @@ async function initCommand(_options) {
 }
 function generateConfigFile(answers) {
   const isTypeScript = answers.outputFormat === "typescript";
+  const useESM = answers.moduleType === "esm";
   if (isTypeScript) {
     return `import { defineConfig } from "strapi2front";
 
@@ -461,6 +509,44 @@ export default defineConfig({
   // Strapi version
   strapiVersion: "${answers.strapiVersion}",
 });
+`;
+  }
+  if (useESM) {
+    return `// @ts-check
+import { defineConfig } from "strapi2front";
+
+export default defineConfig({
+  // Strapi connection
+  url: process.env.STRAPI_URL || "${answers.strapiUrl}",
+  token: process.env.STRAPI_TOKEN,
+
+  // API prefix (default: "/api")
+  apiPrefix: "${answers.apiPrefix}",
+
+  // Output format: "typescript" (.ts) or "jsdoc" (.js with JSDoc)
+  outputFormat: "jsdoc",
+
+  // Module type: auto-detected as ESM
+  moduleType: "esm",
+
+  // Output configuration
+  output: {
+    path: "${answers.outputDir}",
+    types: "types",
+    services: "services",
+    structure: 'by-feature' // or 'by-layer'
+  },
+
+  // Features to generate
+  features: {
+    types: true,
+    services: ${answers.generateServices},
+    actions: false, // Actions require TypeScript
+  },
+
+  // Strapi version
+  strapiVersion: "${answers.strapiVersion}",
+});
 `;
   }
   return `// @ts-check
@@ -500,7 +586,7 @@ module.exports = defineConfig({
 async function appendToEnvFile(envPath, variables) {
   let content = "";
   try {
-    content = await fs4.readFile(envPath, "utf-8");
+    content = await fs5.readFile(envPath, "utf-8");
   } catch {
   }
   const lines = content.split("\n");
@@ -516,39 +602,9 @@ async function appendToEnvFile(envPath, variables) {
   if (newLines.length > 0) {
     const separator = content.endsWith("\n") || content === "" ? "" : "\n";
     const newContent = content + separator + newLines.join("\n") + "\n";
-    await fs4.writeFile(envPath, newContent, "utf-8");
-  }
-}
-async function detectModuleType(cwd = process.cwd()) {
-  try {
-    const packageJsonPath = path6.join(cwd, "package.json");
-    const content = await fs4.readFile(packageJsonPath, "utf-8");
-    const packageJson = JSON.parse(content);
-    if (packageJson.type === "module") {
-      return { type: "esm", reason: 'package.json has "type": "module"' };
-    }
-    if (packageJson.type === "commonjs") {
-      return { type: "commonjs", reason: 'package.json has "type": "commonjs"' };
-    }
-  } catch {
-  }
-  const esmIndicators = [
-    "next.config.mjs",
-    "nuxt.config.mjs",
-    "vite.config.mjs",
-    "astro.config.mjs"
-  ];
-  for (const file of esmIndicators) {
-    try {
-      await fs4.access(path6.join(cwd, file));
-      return { type: "esm", reason: `Found ${file} (ESM config file)` };
-    } catch {
-    }
+    await fs5.writeFile(envPath, newContent, "utf-8");
   }
-  return { type: "commonjs", reason: "Default (no ESM indicators found)" };
 }
-
-// src/commands/sync.ts
 var BLOCKS_RENDERER_PACKAGE = "@strapi/blocks-react-renderer";
 function schemaHasBlocks(schema) {
   const fieldsFound = [];