feat: overlays

Author: jherr

src/add-ons.ts

@@ -139,7 +139,7 @@ function loadAddOn(addOn: AddOn): AddOn {
   return addOn
 }
 
-async function loadRemoteAddOn(url: string): Promise<AddOn> {
+export async function loadRemoteAddOn(url: string): Promise<AddOn> {
   const response = await fetch(url)
   const fileContent = await response.json()
   fileContent.id = url

src/cli.ts

@@ -114,6 +114,7 @@ export function cli() {
       },
     )
     .option('--list-add-ons', 'list all available add-ons', false)
+    .option('--overlay [url]', 'add an overlay from a URL', false)
     .option('--mcp', 'run the MCP server', false)
     .option('--mcp-sse', 'run the MCP server in SSE mode', false)
     .action(async (projectName: string, options: CliOptions) => {

src/config-file.ts

@@ -15,7 +15,7 @@ export type PersistedOptions = Exclude<
 export async function writeConfigFile(
   environment: Environment,
   targetDir: string,
-  options: Required<Options>,
+  options: Options,
 ) {
   const persistedOptions: PersistedOptions = {
     ...options,

src/create-app.ts

@@ -43,7 +43,7 @@ function jsSafeName(name: string) {
 function createTemplateFile(
   environment: Environment,
   projectName: string,
-  options: Required<Options>,
+  options: Options,
   targetDir: string,
 ) {
   return async function templateFile(
@@ -140,7 +140,7 @@ function createTemplateFile(
 async function createPackageJSON(
   environment: Environment,
   projectName: string,
-  options: Required<Options>,
+  options: Options,
   templateDir: string,
   routerDir: string,
   targetDir: string,
@@ -278,7 +278,7 @@ async function copyAddOnFile(
 }
 
 export async function createApp(
-  options: Required<Options>,
+  options: Options,
   {
     silent = false,
     environment,
@@ -486,6 +486,13 @@ export async function createApp(
         }
       }
     }
+    if (options.overlay) {
+      if (options.overlay.shadcnComponents) {
+        for (const component of options.overlay.shadcnComponents) {
+          shadcnComponents.add(component)
+        }
+      }
+    }
 
     if (shadcnComponents.size > 0) {
       s?.start(
@@ -664,13 +671,11 @@ export async function createApp(
   // Create the README.md
   await templateFile(templateDirBase, 'README.md.ejs')
 
-  // Adding overlays
-  for (const addOn of options.chosenAddOns.filter(
-    (addOn) => addOn.type === 'overlay',
-  )) {
-    s?.start(`Setting up overlay ${addOn.name}...`)
-    await runAddOn(addOn)
-    s?.stop(`Overlay ${addOn.name} setup complete`)
+  // Adding overlay
+  if (options.overlay) {
+    s?.start(`Setting up overlay ${options.overlay.name}...`)
+    await runAddOn(options.overlay)
+    s?.stop(`Overlay ${options.overlay.name} setup complete`)
   }
 
   // Install dependencies

src/options.ts

@@ -14,14 +14,14 @@ import {
 } from './package-manager.js'
 import { DEFAULT_TOOLCHAIN, SUPPORTED_TOOLCHAINS } from './toolchain.js'
 import { CODE_ROUTER, DEFAULT_FRAMEWORK, FILE_ROUTER } from './constants.js'
-import { finalizeAddOns, getAllAddOns } from './add-ons.js'
+import { finalizeAddOns, getAllAddOns, loadRemoteAddOn } from './add-ons.js'
 
-import type { AddOn, CliOptions, Options, Variable } from './types.js'
+import type { AddOn, CliOptions, Options, Overlay, Variable } from './types.js'
 
 // If all CLI options are provided, use them directly
 export async function normalizeOptions(
   cliOptions: CliOptions,
-): Promise<Required<Options> | undefined> {
+): Promise<Options | undefined> {
   // in some cases, if you use windows/powershell, the argument for addons
   // if sepparated by comma is not really passed as an array, but as a string
   // with spaces, We need to normalize this edge case.
@@ -42,14 +42,32 @@ export async function normalizeOptions(
       tailwind = true
     }
 
+    let mode: typeof FILE_ROUTER | typeof CODE_ROUTER =
+      cliOptions.template === 'file-router' ? FILE_ROUTER : CODE_ROUTER
+
+    const overlay = cliOptions.overlay
+      ? ((await loadRemoteAddOn(cliOptions.overlay)) as Overlay)
+      : undefined
+
+    if (overlay) {
+      tailwind = overlay.tailwind
+      typescript = overlay.typescript
+      cliOptions.framework = overlay.framework
+      mode = overlay.mode
+    }
+
     let addOns = false
     let chosenAddOns: Array<AddOn> = []
-    if (Array.isArray(cliOptions.addOns)) {
+    if (Array.isArray(cliOptions.addOns) || overlay?.dependsOn) {
       addOns = true
+      let finalAddOns = [...(overlay?.dependsOn || [])]
+      if (cliOptions.addOns && Array.isArray(cliOptions.addOns)) {
+        finalAddOns = [...finalAddOns, ...cliOptions.addOns]
+      }
       chosenAddOns = await finalizeAddOns(
         cliOptions.framework || DEFAULT_FRAMEWORK,
         cliOptions.template === 'file-router' ? FILE_ROUTER : CODE_ROUTER,
-        cliOptions.addOns,
+        finalAddOns,
       )
       tailwind = true
       typescript = true
@@ -65,11 +83,12 @@ export async function normalizeOptions(
         getPackageManager() ||
         DEFAULT_PACKAGE_MANAGER,
       toolchain: cliOptions.toolchain || DEFAULT_TOOLCHAIN,
-      mode: cliOptions.template === 'file-router' ? FILE_ROUTER : CODE_ROUTER,
+      mode,
       git: !!cliOptions.git,
       addOns,
       chosenAddOns,
       variableValues: {},
+      overlay,
     }
   }
 }

src/types.ts

@@ -16,6 +16,7 @@ export interface Options {
   chosenAddOns: Array<AddOn>
   git: boolean
   variableValues: Record<string, string | number | boolean>
+  overlay?: AddOn | undefined
 }
 
 export interface CliOptions {
@@ -30,6 +31,7 @@ export interface CliOptions {
   listAddOns?: boolean
   mcp?: boolean
   mcpSse?: boolean
+  overlay?: string
 }
 
 export type Environment = {
@@ -102,3 +104,15 @@ export type AddOn = {
   files?: Record<string, string>
   deletedFiles?: Array<string>
 }
+
+export type Overlay = AddOn & {
+  type: 'overlay'
+  version: string
+  author: string
+  link: string
+  license: string
+  mode: typeof CODE_ROUTER | typeof FILE_ROUTER
+  framework: Framework
+  typescript: boolean
+  tailwind: boolean
+}