Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: rework component onboarding in launchpad #25713

Merged
merged 40 commits into from
Feb 13, 2023
Merged
Show file tree
Hide file tree
Changes from 34 commits
Commits
Show all changes
40 commits
Select commit Hold shift + click to select a range
b920973
chore: refactoring and types
lmiller1990 Feb 3, 2023
9af7df5
rework source of frameworks
lmiller1990 Feb 3, 2023
b0e6a54
revert rename
lmiller1990 Feb 3, 2023
8685358
fix tests
lmiller1990 Feb 6, 2023
7f46405
Merge remote-tracking branch 'origin/develop' into lmiller/ct-public-…
lmiller1990 Feb 6, 2023
bd446d7
fix more tests
lmiller1990 Feb 6, 2023
169fd2d
types
lmiller1990 Feb 6, 2023
9a58381
update code
lmiller1990 Feb 6, 2023
fe5c399
use same public API internally
lmiller1990 Feb 6, 2023
04eff95
Merge remote-tracking branch 'origin/develop' into lmiller/ct-public-…
lmiller1990 Feb 6, 2023
c9dc13b
rename interfaces
lmiller1990 Feb 6, 2023
57a8c33
rename
lmiller1990 Feb 6, 2023
9582e8d
work on dev server api
lmiller1990 Feb 7, 2023
aa03f22
fix types
lmiller1990 Feb 7, 2023
55eeadf
fix test
lmiller1990 Feb 7, 2023
2c722c3
attempt to support getDevServerConfig
lmiller1990 Feb 7, 2023
6c73ff5
tests
lmiller1990 Feb 7, 2023
7d3535f
add function to define framework [skip ci]
lmiller1990 Feb 7, 2023
2ae85c0
rework a lot of types
lmiller1990 Feb 7, 2023
b8ff1a0
fix test
lmiller1990 Feb 7, 2023
e9257c7
update tests and types
lmiller1990 Feb 7, 2023
681294a
Merge remote-tracking branch 'origin/feature/ct-public-api' into lmil…
lmiller1990 Feb 8, 2023
08dba6b
refactor
lmiller1990 Feb 8, 2023
1d959ae
revert changes
lmiller1990 Feb 8, 2023
3dbd6c1
lint
lmiller1990 Feb 8, 2023
54fee26
fix test
lmiller1990 Feb 8, 2023
b441be4
revert
lmiller1990 Feb 8, 2023
57c2ab9
remove
lmiller1990 Feb 8, 2023
bf884c7
add "community" label [skip ci]
lmiller1990 Feb 8, 2023
33feea4
refactor
lmiller1990 Feb 10, 2023
c8087c1
types
lmiller1990 Feb 10, 2023
270e4e7
lint
lmiller1990 Feb 10, 2023
5060900
fix bug
lmiller1990 Feb 10, 2023
6d6d718
update function name
lmiller1990 Feb 10, 2023
29c8b45
Merge branch 'feature/ct-public-api' into lmiller/ct-public-api-refactor
ZachJW34 Feb 10, 2023
08b705a
address feedback
ZachJW34 Feb 10, 2023
82fe744
improve types with Pick
lmiller1990 Feb 12, 2023
da254fd
refactor using type guard
lmiller1990 Feb 12, 2023
988142c
Merge branch 'feature/ct-public-api' into lmiller/ct-public-api-refactor
lmiller1990 Feb 12, 2023
45bbd45
correct label
lmiller1990 Feb 12, 2023
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions cli/index.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ export default cypress

export const defineConfig = cypress.defineConfig

export const defineComponentFramework = cypress.defineComponentFramework

export const run = cypress.run

export const open = cypress.open
Expand Down
18 changes: 18 additions & 0 deletions cli/lib/cypress.js
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,24 @@ const cypressModuleApi = {
defineConfig (config) {
return config
},

/**
* Provides automatic code completion for Component Frameworks Definitions.
* While it's not strictly necessary for Cypress to parse your configuration, we
* recommend wrapping your Component Framework Definition object with `defineComponentFramework()`
* @example
* module.exports = defineComponentFramework({
* type: 'cypress-ct-solid-js'
* // ...
* })
*
* @see ../types/cypress-npm-api.d.ts
* @param {Cypress.ThirdPartyComponentFrameworkDefinition} config
* @returns {Cypress.ThirdPartyComponentFrameworkDefinition} the configuration passed in parameter
*/
defineComponentFramework (config) {
return config
},
}

module.exports = cypressModuleApi
16 changes: 16 additions & 0 deletions cli/types/cypress-npm-api.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -393,6 +393,22 @@ declare module 'cypress' {
* @returns {Cypress.ConfigOptions} the configuration passed in parameter
*/
defineConfig<ComponentDevServerOpts = any>(config: Cypress.ConfigOptions<ComponentDevServerOpts>): Cypress.ConfigOptions

/**
* Provides automatic code completion for Component Frameworks Definitions.
* While it's not strictly necessary for Cypress to parse your configuration, we
* recommend wrapping your Component Framework Definition object with `defineComponentFramework()`
* @example
* module.exports = defineComponentFramework({
* type: 'cypress-ct-solid-js'
* // ...
* })
*
* @see ../types/cypress-npm-api.d.ts
* @param {Cypress.ThirdPartyComponentFrameworkDefinition} config
* @returns {Cypress.ThirdPartyComponentFrameworkDefinition} the configuration passed in parameter
*/
defineComponentFramework(config: Cypress.ThirdPartyComponentFrameworkDefinition): Cypress.ThirdPartyComponentFrameworkDefinition
}

// export Cypress NPM module interface
Expand Down
171 changes: 171 additions & 0 deletions cli/types/cypress.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3244,6 +3244,177 @@ declare namespace Cypress {

type PickConfigOpt<T> = T extends keyof DefineDevServerConfig ? DefineDevServerConfig[T] : any

interface DependencyToInstall {
dependency: CypressComponentDependency
satisfied: boolean
loc: string | null
detectedVersion: string | null
}

interface CypressComponentDependency {
/**
* Unique idenitifer.
* @example 'reactscripts'
*/
type: string

/**
* Name to display in the user interface.
* @example "React Scripts"
*/
name: string

/**
* Package name on npm.
* @example react-scripts
*/
package: string

/**
* Code to run when installing. Version is optional.
*
* Should be <package_name>@<version>.
*
* @example `react`
* @example `react@18`
* @example `react-scripts`
*/
installer: string

/**
* Description shown in UI. It is recommended to use the same one the package uses on npm.
* @example 'Create React apps with no build configuration'
*/
description: string

/**
* Minimum version supported. Should conform to Semantic Versioning as used in `package.json`.
* @see https://docs.npmjs.com/cli/v9/configuring-npm/package-json#dependencies
* @example '^=4.0.0 || ^=5.0.0'
* @example '^2.0.0'
*/
minVersion: string
}

interface ResolvedComponentFrameworkDefinition {
/**
* A semantic, unique identifier. Must begin with `cypress-ct-` for third party implementations.
* @example: 'reactscripts', 'nextjs', 'cypress-ct-solid-js'
*/
type: string
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here we say the type must start with cypress-ct-, but the configFramework doesn't have this restriction even though inside of webpack-dev-server/src/devServer.ts we expect it to also have this same restriction. Looks like they should be the same or at least both should share the cypress-ct- prefix

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm good point, maybe we just expose name in the public API and for third parties, in processFrameworkDefinition, do

configFramework = name

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So configFramework will be @private

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done


/**
* Used as the flag for `getPreset` for meta framworks, such as finding the webpack config for CRA, Angular, etc.
*
* configFramwork: () => {
* return getSolidJsMetaFrameworkBundlerConfig()
* }
* It is also the name of the string added to `cypress.config`
*
* @example
*
* export default {
* component: {
* devServer: {
* framework: 'create-react-app' // can be 'next', 'create-react-app', etc etc.
* }
* }
* }
*/
configFramework: string

/**
* Library (React, Vue) or template (aka "meta framework") (CRA, Next.js, Angular)
*/
category: 'library' | 'template'

/**
* Name displayed in Launchpad when doing initial setup.
* @example 'Solid.js', 'Create React App'
*/
name: string

/**
* Supported bundlers.
*/
supportedBundlers: Array<'webpack' | 'vite'>

/**
* Used to attempt to automatically select the correct framework/bundler from the dropdown.
* @example
*
* const SOLID_DETECTOR: Dependency = {
* type: 'solid',
* name: 'Solid.js',
* package: 'solid-js',
* installer: 'solid-js',
* description: 'Solid is a declarative JavaScript library for creating user interfaces',
* minVersion: '^1.0.0',
* }
*/
detectors: CypressComponentDependency[]

/**
* Array of required dependencies. This could be the bundler and JavaScript library.
* It's the same type as `detectors`.
*/
dependencies: (bundler: 'webpack' | 'vite', projectPath: string) => Promise<DependencyToInstall[]>

/**
* @internal
* This is used interally by Cypress for the "Create From Component" feature.
*/
codeGenFramework?: 'react' | 'vue' | 'svelte' | 'angular'

/**
* @internal
* This is used interally by Cypress for the "Create From Component" feature.
* @example '*.{js,jsx,tsx}'
*/
glob?: string

/**
* This is the path to get mount, eg `import { mount } from <mount_module>,
* @example: `cypress-ct-solidjs/src/mount`
*/
mountModule: (projectPath: string) => Promise<string>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mentioned this in the tech-brief but I'm curious what you think of making the ThirdPartyComponentFrameworkDefinition have mountModule: string for simplicity?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point, I was trying to make the APIs as similar as possible but it's probably not worth it - better to opt for some internal complexity and expose a nicer public API

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't need mountModule at all for third parties now... https://github.com/cypress-io/engineering-documentation/pull/71

Since we assume it's named export from the default entry point, we can assume import { mount } from '<package>' is valid.


/**
* Support status. Internally alpha | beta | full.
* Community integrations are "community".
* @internal
*/
supportStatus: 'alpha' | 'beta' | 'full' | 'community'

/**
* Function returning string for used for the component-index.html file.
* Cypress provides a default if one isn't specified for third party integrations.
*/
componentIndexHtml?: () => string

/**
* Used for the Create From Comopnent feature.
* This is currently not supported for third party frameworks.
* @internal
*/
specPattern?: '**/*.cy.ts'
}

type ComponentFrameworkDefinition = Omit<ResolvedComponentFrameworkDefinition, 'dependencies'> & {
dependencies: (bundler: 'webpack' | 'vite') => CypressComponentDependency[]
}

// Certain properties are not supported for third party frameworks right now, such as ones related to the "Create From" feature.
type ThirdPartyComponentFrameworkDefinition = Omit<ComponentFrameworkDefinition, 'glob' | 'codeGenFramework' | 'supportStatus' | 'specPattern' | 'mountModule' | 'configFramework' | 'type' | 'category'> & {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit - might be better to make this an inclusion (Pick) vs exclusion (Omit). Would force us to be more deliberate about what to expose going forward if we add new fields to the internal types

type ThirdPartyComponentFrameworkDefinition = Pick<ComponentFrameworkDefinition, 'name' | 'supportedBundlers' | 'detectors' | 'dependencies' | 'componentIndexHtml'>

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Smart, let's do that.

type: `cypress-ct-${string}`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, cool, I didn't know you could do this kind of string pattern enforcement with TS 🆒

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not a feature supported in older versions of Typescript. Unless we drop versions of typescript that don't support template strings we'll have to go with string

Copy link
Contributor Author

@lmiller1990 lmiller1990 Feb 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm this is a good point - this feature was added in TS 4.1 https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-1.html. Released 2 years ago.

The most popular pre 4.1 version is 3.9.7
with 385k - the latest 4.x has has 6.5M.

We could do

`cypress-ct-${string}` | string

Since our minimum version of TS is 3.4: https://docs.cypress.io/guides/tooling/typescript-support#Install-TypeScript


/**
* Only `library` is supported for third party definitions.
* `template` will be supported in the future.
*/
category: 'library'
}

interface AngularDevServerProjectConfig {
root: string
sourceRoot: string
Expand Down
29 changes: 28 additions & 1 deletion cli/types/tests/cypress-npm-api-test.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
// type tests for Cypress NPM module
// https://on.cypress.io/module-api
import cypress, { defineConfig } from 'cypress'
import cypress, { defineComponentFramework, defineConfig } from 'cypress'

cypress.run // $ExpectType (options?: Partial<CypressRunOptions> | undefined) => Promise<CypressRunResult | CypressFailedRunResult>
cypress.open // $ExpectType (options?: Partial<CypressOpenOptions> | undefined) => Promise<void>
Expand Down Expand Up @@ -55,6 +55,33 @@ const config = defineConfig({
modifyObstructiveCode: true
})

const solid = {
type: 'solid-js',
name: 'Solid.js',
package: 'solid-js',
installer: 'solid-js',
description: 'Solid is a declarative JavaScript library for creating user interfaces',
minVersion: '^1.0.0'
}

const thirdPartyFrameworkDefinition = defineComponentFramework({
type: 'cypress-ct-third-party',
name: 'Third Party',
category: 'library',
dependencies: (bundler) => [solid],
detectors: [solid],
supportedBundlers: ['vite', 'webpack']
})

const thirdPartyFrameworkDefinitionInvalidStrings = defineComponentFramework({
type: 'cypress-not-cy-wrong-prefix', // $ExpectError
name: 'Third Party',
category: 'template', // $ExpectError - only library supported for third party definitions
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
category: 'template', // $ExpectError - only library supported for third party definitions
// only library supported for third party definitions
category: 'template', // $ExpectError

Looks like the syntax for dtslint is pretty strict, the extra comment following the assertion messes with this check

dependencies: (bundler) => [],
detectors: [{}], // $ExpectError
supportedBundlers: ['metro', 'webpack'] // $ExpectError
})

// component options
const componentConfigNextWebpack: Cypress.ConfigOptions = {
component: {
Expand Down
9 changes: 8 additions & 1 deletion npm/webpack-dev-server/src/devServer.ts
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,13 @@ export type PresetHandlerResult = { frameworkConfig: Configuration, sourceWebpac
type Optional<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>

async function getPreset (devServerConfig: WebpackDevServerConfig): Promise<Optional<PresetHandlerResult, 'frameworkConfig'>> {
const defaultWebpackModules = () => ({ sourceWebpackModulesResult: sourceDefaultWebpackDependencies(devServerConfig) })

// Third party library (eg solid-js, lit, etc)
if (devServerConfig.framework?.startsWith('cypress-ct-')) {
return defaultWebpackModules()
}

switch (devServerConfig.framework) {
case 'create-react-app':
return createReactAppHandler(devServerConfig)
Expand All @@ -134,7 +141,7 @@ async function getPreset (devServerConfig: WebpackDevServerConfig): Promise<Opti
case 'vue':
case 'svelte':
case undefined:
return { sourceWebpackModulesResult: sourceDefaultWebpackDependencies(devServerConfig) }
return defaultWebpackModules()

default:
throw new Error(`Unexpected framework ${(devServerConfig as any).framework}, please visit https://on.cypress.io/component-framework-configuration to see a list of supported frameworks`)
Expand Down
5 changes: 2 additions & 3 deletions packages/data-context/src/actions/CodegenActions.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@ import type { DataContext } from '..'
import { SpecOptions, codeGenerator } from '../codegen'
import templates from '../codegen/templates'
import type { CodeGenType } from '../gen/graphcache-config.gen'
import { WizardFrontendFramework, WIZARD_FRAMEWORKS } from '@packages/scaffold-config'
import { parse as parseReactComponent, resolver as reactDocgenResolvers } from 'react-docgen'
import { visit } from 'ast-types'

Expand Down Expand Up @@ -152,7 +151,7 @@ export class CodegenActions {
})
}

getWizardFrameworkFromConfig (): WizardFrontendFramework | undefined {
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In general I think we should move away from naming things "Wizard". 🧙 are pretty cool, but it's probably a confusing, considering these are used throughout the entire app, not just in the Launchpad wizard.

We should just call them ComponentFrontendFramework, since that's what they are.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree Wizards are pretty cool

getWizardFrameworkFromConfig (): Cypress.ResolvedComponentFrameworkDefinition | undefined {
const config = this.ctx.lifecycleManager.loadedConfigFile

// If devServer is a function, they are using a custom dev server.
Expand All @@ -161,7 +160,7 @@ export class CodegenActions {
}

// @ts-ignore - because of the conditional above, we know that devServer isn't a function
return WIZARD_FRAMEWORKS.find((framework) => framework.configFramework === config?.component?.devServer.framework)
return this.ctx.coreData.wizard.frameworks.find((framework) => framework.configFramework === config?.component?.devServer.framework)
}
}

Expand Down
Loading