[App Extensibility] Update documentation of the extension-base package (used for generating a new extension) (@W-17018677@)

packages/extension-base/README.md

@@ -5,6 +5,13 @@ _\ \ (_| | | | | | | |_) | |  __/ //__  >  <| ||  __/ | | \__ \ | (_) | | | |
 \__/\__,_|_| |_| |_| .__/|_|\___| \__/ /_/\_\\__\___|_| |_|___/_|\___/|_| |_|
                    |_|                                                       
 
+TODO
+- assets
+- types
+- default, sample configs, plus useExtensionConfig
+- overrides and overridable
+- review recent feedback from offsite?
+
 # Description
 
 This is a sample PWA-Kit Application Extension. The purpose of this application extensions is to show how
@@ -50,6 +57,7 @@ the extension as they like.
 ```
 
 # Installation
+TODO: update this
 
 ```
 > npm install @salesforce/extension-sample<br/>

packages/extension-base/config/README.md

@@ -0,0 +1,4 @@
+TODO: mention default, sample configs, plus useExtensionConfig
+- Differentiate between the app config and this config
+- Merge between user defined config and extensions default config
+- configurable vs overridable?

packages/extension-base/package.json

@@ -28,6 +28,7 @@
     "@salesforce/pwa-kit-extension-sdk": "4.0.0-extensibility-preview.3",
     "@salesforce/pwa-kit-react-sdk": "4.0.0-extensibility-preview.3",
     "@salesforce/pwa-kit-runtime": "4.0.0-extensibility-preview.3",
+    "@types/express": "^5.0.0",
     "@types/loadable__component": "^5.13.9",
     "@types/react": "~18.2.0",
     "@types/react-dom": "~18.2.1",

packages/extension-base/src/components/with-red-border.tsx → packages/extension-base/src/components/with-sample-component.tsx

@@ -8,19 +8,19 @@
 import React from 'react'
 
 // Define a type for the HOC props
-type WithRedBorderProps = React.ComponentPropsWithoutRef<any>
+type WithSampleComponentProps = React.ComponentPropsWithoutRef<any>
 
 // Define the HOC function
-const withRedBorder = <P extends object>(WrappedComponent: React.ComponentType<P>) => {
-    const WithRedBorder: React.FC<P> = (props: WithRedBorderProps) => {
+const withSampleComponent = <P extends object>(WrappedComponent: React.ComponentType<P>) => {
+    const WithSampleComponent: React.FC<P> = (props: WithSampleComponentProps) => {
         return (
-            <div style={{border: '2px solid red', padding: '10px'}}>
+            <div className="sample-component">
                 <WrappedComponent {...(props as P)} />
             </div>
         )
     }
 
-    return WithRedBorder
+    return WithSampleComponent
 }
 
-export default withRedBorder
+export default withSampleComponent

packages/extension-base/src/pages/sample.tsx

@@ -22,30 +22,6 @@ const Sample = () => {
                 If you are reading this, it means that this page was successfully added to your base
                 project. 🎉
             </p>
-            <p>
-                This <i>Application Extension</i> was installed by running the below command in your
-                PWA-Kit project. Its dependancies were automatically installed and the extension
-                configured into your projects extensions array.
-            </p>
-            <div
-                style={{
-                    border: '1px solid darkGray',
-                    backgroundColor: 'lightgray',
-                    width: 'calc(100% - 10px)',
-                    padding: '5px'
-                }}
-            >
-                <code>
-                    &gt; npm install @salesforce/extension-sample
-                    <br />
-                    &gt; Downloading npm package... <br />
-                    &gt; Installing extention... <br />
-                    &gt; Finished. <br />
-                    &gt; Congratulations! The Sample extension was successfully installed! Please
-                    visit https://www.npmjs.com/package/@salesforce/extension-sample for more
-                    information on how to use this extension.
-                </code>
-            </div>
         </Fragment>
     )
 }

packages/extension-base/src/setup-app.ts

@@ -14,11 +14,16 @@ import {ApplicationExtension} from '@salesforce/pwa-kit-extension-sdk/react'
 
 // Local Imports
 import {Config} from './types'
-import withRedBorder from 'overridable!./components/with-red-border'
 import SamplePage from './pages/sample'
-
 import extensionMeta from '../extension-meta.json'
 
+// By importing this SampleComponent via the overridable loader,
+// you intentionally make it available for other extensions or a user project to override the file
+import withSampleComponent from 'overridable!./components/with-sample-component'
+// Then others can override it by creating a file in this overrides directory:
+// - for another extension: src/overrides/<name of your extension>/components/with-sample-component.tsx
+// - for a user project: app/overrides/<name of your extension>/components/with-sample-component.tsx
+
 class Sample extends ApplicationExtension<Config> {
     static readonly id = extensionMeta.id
 
@@ -30,7 +35,8 @@ class Sample extends ApplicationExtension<Config> {
     extendApp<T extends React.ComponentType<T>>(
         App: React.ComponentType<T>
     ): React.ComponentType<T> {
-        return withRedBorder(App)
+        // For example, you can extend the React app by wrapping your project's App with this SampleComponent
+        return withSampleComponent(App)
     }
 
     /**

packages/extension-base/src/setup-server.ts

@@ -15,17 +15,17 @@ import {ApplicationExtension} from '@salesforce/pwa-kit-extension-sdk/express'
 import {Config} from './types'
 import extensionMeta from '../extension-meta.json'
 
-class SampleExtension extends ApplicationExtension<Config> {
+class Sample extends ApplicationExtension<Config> {
     static readonly id = extensionMeta.id
 
     /**
      * Use this method to enhance or modify your ExpressJS Application by adding route handlers and middleware.
      */
     extendApp(app: Application): Application {
+        // For example, you can extend the Express app by creating a new endpoint like this.
         app.get('/sample', (req, res) => {
-            console.log('SampleExtension extendApp GET /sample')
             res.send(
-                `<p>Hello from an express SampleExtension!</p>
+                `<p>Hello from a sample endpoint! Created by ${Sample.id}.</p>
                 <pre>extensionConfig = ${JSON.stringify(this.getConfig())}</pre>`
             )
         })
@@ -34,4 +34,4 @@ class SampleExtension extends ApplicationExtension<Config> {
     }
 }
 
-export default SampleExtension
+export default Sample

packages/extension-base/static/README.md

@@ -0,0 +1 @@
+TODO

packages/extension-sample/src/setup-app.ts

@@ -19,6 +19,8 @@ import {Config} from './types'
 import SamplePage from './pages/sample'
 import extensionMeta from '../extension-meta.json'
 
+// TODO: do we still need extension-sample directory? can we safely remove it?
+// I see related presets in the generator that use the extension-sample. In this case, can we swap it with extension-base?
 class Sample extends ApplicationExtension<Config> {
     static readonly id = extensionMeta.id
 

packages/pwa-kit-create-app/scripts/create-mobify-app.js

@@ -119,7 +119,7 @@ const TEMPLATE_SOURCE_NPM = 'npm'
 const TEMPLATE_SOURCE_BUNDLE = 'bundle'
 const DEFAULT_TEMPLATE_VERSION = 'latest'
 
-const LOCAL_DEV_PROJECT_DIR = 'dev'
+const LOCAL_DEV_PROJECT_DIR = 'sample-app'
 
 const INITIAL_QUESTION = [
     {
@@ -964,7 +964,7 @@ const runGenerator = async (
                 templateSource: {type: TEMPLATE_SOURCE_BUNDLE, id: 'typescript-minimal'},
                 private: true
             },
-            answers: {project: {type: 'PWAKitAppProject', name: 'local-dev-project'}}
+            answers: {project: {type: 'PWAKitAppProject', name: 'sample-app'}}
         }
 
         await runGenerator(localDevProjectContext, {
@@ -1036,35 +1036,40 @@ const runGenerator = async (
         npmInstall(outputDir, {verbose, projectName: context.answers.project.name})
     }
 
-    const extensionsWithDefaultConfig = selectedAppExtensions.map((extension) => {
-        // Since we've just installed the dependencies, we can read the default config of each extension
-        const pathToDefaultConfig = p.join(
-            outputDir,
-            'node_modules',
-            extension,
-            'config',
-            'default.json'
-        )
-        if (!fs.existsSync(pathToDefaultConfig)) {
-            console.warn(
-                `The extension ${extension} does not have a default config. Will generate a minimal default config for it.`
+    if (selectedAppExtensions.length > 0) {
+        const extensionsWithDefaultConfig = selectedAppExtensions.map((extension) => {
+            // Since we've just installed the dependencies, we can read the default config of each extension
+            const pathToDefaultConfig = p.join(
+                outputDir,
+                'node_modules',
+                extension,
+                'config',
+                'default.json'
             )
-            // Return a minimal default config. It should match what's defined in: https://github.com/SalesforceCommerceCloud/pwa-kit/blob/310e946bed12fd4cbb42a209ee6982e9b1bb9b99/packages/pwa-kit-extension-sdk/src/shared/utils/helpers.ts#L13-L15
-            return [extension, {enabled: true}]
-        }
+            if (!fs.existsSync(pathToDefaultConfig)) {
+                console.warn(
+                    `The extension ${extension} does not have a default config. Will generate a minimal default config for it.`
+                )
+                // Return a minimal default config. It should match what's defined in: https://github.com/SalesforceCommerceCloud/pwa-kit/blob/310e946bed12fd4cbb42a209ee6982e9b1bb9b99/packages/pwa-kit-extension-sdk/src/shared/utils/helpers.ts#L13-L15
+                return [extension, {enabled: true}]
+            }
 
-        const defaultConfig = readJson(pathToDefaultConfig)
-        return [extension, defaultConfig]
-    })
-    updatePackageJson(p.resolve(outputDir, 'package.json'), {
-        ...(selectedAppExtensions.length > 0 && {
+            const defaultConfig = readJson(pathToDefaultConfig)
+            return [extension, defaultConfig]
+        })
+
+        updatePackageJson(p.resolve(outputDir, 'package.json'), {
             mobify: {
                 app: {
                     extensions: extensionsWithDefaultConfig
                 }
             }
         })
-    })
+
+        console.log(
+            'After your project is generated, please review `mobify.app.extensions` in package.json to check the configuration of the extensions and fill out any placeholder values.'
+        )
+    }
 }
 
 const foundNode = process.versions.node