20 Replies Latest reply on Sep 25, 2017 7:55 AM by sberic

    TypeScript Enabled CEP Development

    sberic Level 2

      Modern Tools and ExtendScript

      Earlier this week, Bruce Bullis integrated a pull request into the CEP Samples repository that included a new Sample called TypeScript. TypeScript is a language that "transpiles" into JavaScript and JavaScript-based languages (e.g. ExtendScript). It can also be configured in certain environments (e.g. Visual Studio Code) to provide normal JavaScript (and, it turns out, ExtendScript) development with helpful type checking and IntelliSense/autocompletion support. Here's an example:

      TSExample.gif

      Open the PProPanel-vscode folder in Visual Studio Code (or other TypeScript-aware IDEs?), open up the Premiere.jsx file, and simply begin typing. The environment is already set up to provide rich IntelliSense support.

       

      Powered By TypeScript Declaration Files and JSDoc

      The environment has to get information about the types from somewhere, right? The type information is identified by the TypeScript system in the following ways:

       

      • In the Panel JavaScript Environment:
      • In the App ExtendScript Environment:
        • Uses the TypeScript-provided ES5 type information (ES3 is coming - when available, it will be switched to use that!).
        • Uses custom Type Declaration files (included within the sample here) to help make the IDE aware of what types are available, as well as documentation!
        • Sources JSDoc comments for type information.

       

      Beyond this, TypeScript is capable of type inference (set var x = 5; and the IDE will infer that x is a number). For more on how TypeScript does all of this, see this document.

       

      Inline ExtendScript and PremierPro API Documentation

      The declaration files included in the sample are currently incomplete, but Bruce Bullis has indicated interest in helping to fill in the blanks. These files are an improvement over the current documentation in that they can be [more] easily read on the web (don't need to be downloaded and opened in a browser) and also power in-line documentation and suggestions (as in the above gif)!

       

      Writing in TypeScript

      As configured, the sample does not actually assume that you will be writing in TypeScript and transpiling to JavaScript, but that you are simply writing JavaScript/ExtendScript. If you wish to use this feature, you will have to configure your IDE to do so (Visual Studio Code, Webstorm, Sublime Text, etc.).

       

      Writing in NEW JavaScript

      It should also be noted that TypeScript can transpile from new JavaScript to old JavaScript. This may not seem all that interesting except that you could use the latest ES6 features to write code for both your panel JavaScript or your app ExtendScript. These would be transpiled into platform-compatible versions: target: "es5" for panel and target: "es3" for ExtendScript!

       

      As with TypeScript, this use-case would require setting up the TypeScript compiler.

       

      Debugging In Visual Studio Code

      This sample also contains configuration settings to allow debugging of the panel (HTML) environment directly in Visual Studio Code, rather than through a Chrome browser. See:

      vscode-debugging.png

       

      Questions? Comments? Ask/post away!

        • 1. Re: TypeScript Enabled CEP Development
          jingtaotan Level 1

          Very interesting stuff! Thanks Bruce Bullis for the work and sberic for the announcement. Will definitely send feedback (or even submit a pull request) when working with this.

          • 2. Re: TypeScript Enabled CEP Development
            Bruce Bullis Adobe Employee

            [All work = Eric]

            • 3. Re: TypeScript Enabled CEP Development
              pqiorpa Level 1

              I have created guide how to start using TypeScript with Adobe ExtendScript.

              It works with Visual Studio Code too.

              GitHub - pravdomil/types-for-adobe: Use TypeScript for Adobe Audition / Illustator / InDesign / Photoshop

              2 people found this helpful
              • 4. Re: TypeScript Enabled CEP Development
                sberic Level 2

                pqiorpa  wrote

                 

                I have created guide how to start using TypeScript with Adobe ExtendScript.

                It works with Visual Studio Code too.

                GitHub - pravdomil/types-for-adobe: Use TypeScript for Adobe Audition / Illustator / InDesign / Photoshop

                 

                Any thoughts on potentially integrating this into the Adobe CEP TypeScript example?

                 

                I see that you followed the naming convention used by the ExtendScript Toolkit (instead of "ExtendScript APIs" it's "JavaScript APIs"). Did you perhaps use a script to automate conversion of the XML documentation (installed with the toolkit) to TypeScript typings format?

                 

                Either way, I think it would be excellent to get these combined and added to the repo. The goal for the TypeScript example folder was always to expand it's contents beyond the minimal setup it's at now and into a full-fledged ExtendScript environment with proper per-application support (which it seems you've mostly nailed!).

                 

                One further question: are the "JavaScript" typings are feature-complete enough to cover all of the ECMAScript 3 intricacies or not? I notice that you have Object as a class. This is very different from the version provided in TypeScript for ECMAScript 5 (and 3, whenever it gets through review), where Object is an interface (for some important reasons).

                • 5. Re: TypeScript Enabled CEP Development
                  pqiorpa Level 1

                  Now the definition files are ECMAScript 3 compatible. I have converted Object and other core objects into interfaces.

                   

                  Yes I had used convertor to convert XML documentation into TypeScript. You can find it here:

                  GitHub - pravdomil/extendscript-xml-to-typescript: ExtendScript XML documentation to TypeScript converter https://github.com/pravdomil/extendscript-xml-to-typescript

                   

                  About joining with Adobe-CEP example repo: I want to create separate repo for declaration files as it should be (check DefinitelyTyped).

                  Then you can use npm package manager from Node.js to install declaration files from my repository.

                  On top of that, npm will ensure that you have the latest version.

                  I updated readme file, there is now small guide how to create first script for Adobe Illustrator.

                  https://github.com/pravdomil/types-for-adobe/blob/master/README.md

                   

                  BTW: is there any CreativeCloud plans for developers?

                  • 6. Re: TypeScript Enabled CEP Development
                    sberic Level 2

                    pqiorpa  wrote

                     

                    Now the definition files are ECMAScript 3 compatible. I have converted Object and other core objects into interfaces.

                    Awesome!

                     

                    pqiorpa  wrote

                     

                    Yes I had used convertor to convert XML documentation into TypeScript. You can find it here:

                    GitHub - pravdomil/extendscript-xml-to-typescript: ExtendScript XML documentation to TypeScript converter https://github.com/pravdomil/extendscript-xml-to-typescript

                    That's great! Thanks for sharing it!

                     

                    pqiorpa  wrote

                     

                    About joining with Adobe-CEP example repo: I want to create separate repo for declaration files as it should be (check DefinitelyTyped).

                    Then you can use npm package manager from Node.js to install declaration files from my repository.

                    On top of that, npm will ensure that you have the latest version.

                    Hmm... I'd need to look into the requirements for contributing to DefinitelyTyped to speak more about this. One thing that I've discussed with Bruce Bullis is the need for keeping Adobe application version-specific typings available. As you're well aware, different versions of Adobe have different amounts of ExtendScript API support (typically they add more APIs). If you're working on a panel that you'd wish to be compatible back to a certain version, then it would be helpful to specify that version. Does your current setup allow for versioning that matches the Adobe application version? Any thoughts here?

                     

                    Having the entire ExtendScript environment (JavaScript, app-specific libraries, extra features [e.g. ScriptUI], etc.) on npm such that a single well-configured package.json is all that's required for getting up and running with a panel dev-environment would be amazing.

                     

                    pqiorpa  wrote

                     

                    BTW: is there any CreativeCloud plans for developers?

                    This would be more of a question for Bruce Bullis.

                    • 7. Re: TypeScript Enabled CEP Development
                      pqiorpa Level 1

                      Now you can choose what version you want to use, check:

                      GitHub - pravdomil/types-for-adobe: Use TypeScript for Adobe Audition / Illustator / InDesign / Photoshop scripting

                      Any other versions can be easily added by converting xml documentation to index.d.ts with that convertor I mentioned.

                      • 8. Re: TypeScript Enabled CEP Development
                        sberic Level 2

                        pqiorpa  wrote

                         

                        Any other versions can be easily added by converting xml documentation to index.d.ts with that convertor I mentioned.

                        A few questions for you about this:

                         

                        1. Awesome. Version support sounds great. Do you have any comments on the structure? How is it supposed to be updated? How do you access the specific versions? If this is intended to be picked up by DefinitelyTyped, I'd suggest looking at the Node typings repository on DT. Some key notes:
                          1. Node is an application. This is similar to PhotoShop or Illustrator. Therefore, each application should have their own typings "root". This is what the structure looks like for Node:
                            • Node/
                              • index.d.ts - Typings for v8.x.
                              • v0/
                                • index.d.ts - Typings for v0.12.
                              • v4/
                                • index.d.ts - Typings for v4.x.
                              • v6/
                                • index.d.ts - Typings for v6.x.
                              • v7/
                                • index.d.ts - Typings for v7.x.
                          2. Given #1.1 above, perhaps you could do this in your typings repo:
                            • Audition/
                              • index.d.ts - Typings for 2016.1 [if they exist...]
                              • v2015.2/
                                • index.d.ts - Typings for 2015.2.
                            • Illustrator/
                              • index.d.ts - Typings for 2016.1 [if they exist...]
                              • v2015.3/
                                • index.d.ts - Typings for 2015.3.
                            • etc.
                          3. This appears to be in line with what Definitely Type suggests when dealing with new major revisions.
                        2. Your index.d.ts files seem to be missing the standard informational header that is common for DT typings. See this page.

                         

                        I've not published any typings to DT myself, though I've spent some time digging into it a bit to better understand the system. Does this all make sense? Would love to hear any insight you may have!

                         

                        Thoughts?

                        • 9. Re: TypeScript Enabled CEP Development
                          pqiorpa Level 1

                          Well, I have no more plans to publish those types into Definitely Typed. Instead I will keep it i my repo.

                          • 10. Re: TypeScript Enabled CEP Development
                            sberic Level 2

                            pqiorpa  wrote

                             

                            Well, I have no more plans to publish those types into Definitely Typed. Instead I will keep it i my repo.

                            Understood! Thanks for the contributions, regardless. Great work with this!

                             

                            Perhaps Adobe themselves could pick up the ball and run with it. It would be a real nice way to enhance the development environment, especially given how ExtendScript Toolkit may no longer work on macOS once High Sierra ships... Bruce Bullis, any thoughts on this?

                            • 11. Re: TypeScript Enabled CEP Development
                              Naoki-Hada Level 1

                              Hi sberic, pqiorpa,

                               

                              Thank you very much for sharing your code.

                              I went through your code.

                               

                              I'm new to TypeScript.

                              I have been developing CEP plugin about half year and got task to convert

                              semi-large CEP project (multiple Adobe apps support) to TypeScript.

                               

                              Is there any sample CEP project does "transpiles" with multiple Adobe app support?

                              ex) alert(app.version)

                               

                              Thank you,

                              Naoki

                              • 12. Re: TypeScript Enabled CEP Development
                                sberic Level 2

                                Naoki-Hada  wrote

                                 

                                I'm new to TypeScript.

                                I have been developing CEP plugin about half year and got task to convert

                                semi-large CEP project (multiple Adobe apps support) to TypeScript.

                                That sounds like fun! Which apps do you specifically need to convert?

                                 

                                TypeScript is very easy configure for CEP development. You only need to set up a TypeScript context for each of the two separate script domains in the CEP environment:

                                 

                                • A tsconfig.json file for the panel JavaScript.
                                • A tsconfig.json file for the application ExtendScript.

                                 

                                In the tsconfig.json files you need to be aware of the lib and target options.

                                 

                                The lib option allows you to define the ECMAScript environment that your code will be running in. It tells TypeScript which ECMAScript (JavaScript/ExtendScript) functions are available. In the panel (HTML) side, you will have "es5" and some other options because the code is a web browser (Chrome/Chromium). In the app (ExtendScript) side, you will have "es5" because there currently is no option for "es3". Alternatively, you could use pqiorpa's setup with the noLib option instead of lib. Then you use the types option in the tsconfig.json file to specify which apps you want to support (his command line example sets this up).

                                 

                                The target option allows you to define which ECMAScript version the TypeScript compiler should output.  For the panel (HTML) side, you should be okay with "es5" because the more recent versions of Chromium at the base of CEP extensions have support for most of those features. ExtendScript is based on ECMAScript 3 so the app (ExtendScript) side will use "es3".

                                 

                                This is how the sample project is setup. You can see those settings in the project here.

                                 

                                Naoki-Hada  wrote

                                 

                                Is there any sample CEP project does "transpiles" with multiple Adobe app support?

                                ex) alert(app.version)

                                Not that I am aware of, no. It would not be hard with pqiorpa's types, though! You could either include all the typings (.d.ts files) within the Sample Premiere Pro project or simply combine the Sample Premiere Pro project with those typings and adjust the app-side tsconfig.json to use the specific types option. It shouldn't be difficult!

                                1 person found this helpful
                                • 13. Re: TypeScript Enabled CEP Development
                                  Naoki-Hada Level 1

                                  sberic,

                                  Thank you very much for detail explanation.

                                  I think I can do rocket start

                                   

                                  The working CEP plugin is targeting Photoshop, Illustrator, InDesign and Premiere Pro.

                                  As project became larger, it got more issues especially around CSInferface.evalScript().

                                   

                                  I was using WebStorm for IDE.

                                  I'll check with VS Code as well.

                                   

                                  Thank you,

                                  Naoki

                                  • 14. Re: TypeScript Enabled CEP Development
                                    sberic Level 2

                                    Naoki-Hada  wrote

                                     

                                    The working CEP plugin is targeting Photoshop, Illustrator, InDesign and Premiere Pro.

                                    As project became larger, it got more issues especially around CSInferface.evalScript().

                                    Understood. The Premiere Pro typings were created by myself. You will want to mix those with the typings created by pqiorpa. The two were generated using different methods (the Premiere Pro ones were compiled manually from multiple sources, the others were automated). Please don't hesitate to ask questions if/when you run into issues with the environment!

                                     

                                    Naoki-Hada  wrote

                                     

                                    I was using WebStorm for IDE.

                                    I'll check with VS Code as well.

                                    WebStorm has support for TypeScript so you could probably get it working there! One of the benefits of VSCode is that debugging of the HTML Panel code (at least) works within the IDE!

                                    1 person found this helpful
                                    • 15. Re: TypeScript Enabled CEP Development
                                      eyali.av

                                      I'm only a beginner (CEP integration wise and TypeScript wise), there're some basics that I'm aware that I'm lacking.

                                      My question is just to help me get started with TypeScript for the HTML layer and specifically to integrate UI libraries (like https://www.primefaces.org/primeng/#/ for angular environment).

                                      Where is my new TypeScript code should be located and how do I instruct node.js to compile it with the third party libraries (NPM??)?

                                      The sample provided has only .js files - are those the output javascript which generated after node compilation?

                                      • 16. Re: TypeScript Enabled CEP Development
                                        sberic Level 2

                                        eyali.av  wrote

                                         

                                        The sample provided has only .js files - are those the output javascript which generated after node compilation?

                                        The TypeScript Sample shows how you can use a TypeScript-enabled environment to enhance the CEP development experience. CEP development is primarily a JavaScript/ExtendScript-based affair. What the Sample does is sets everything up so that you get IntelliSense support and errors/warnings for JavaScript/ExtendScript files. All of the *.js files in the sample remain unchanged from the main PPro folder from which they were ported (at the time they were ported, at least).

                                         

                                        As such, the TypeScript compiler is not actually used to compile/transpile any TypeScript code in the Sample. In fact, the only *.ts files in the sample are type declaration files (aka "typings"). These provide the TypeScript services with the information necessary to provide the type information to the environment!

                                         

                                        eyali.av  wrote

                                         

                                        Where is my new TypeScript code should be located and how do I instruct node.js to compile it with the third party libraries (NPM??)?

                                        I guess that it's possible to set up the CEP environment to transpile the TypeScript code to JavaScript inside the plugin, but you'd be doing a lot of work for very little, I think. Without understanding your goal (or very much about Angular+Primeng), I would suggest that you only write in TypeScript locally and "ship" your plugin as JavaScript. This would mean writing in TypeScript, committing a "build", and then ensuring that only the JavaScript files ended up in the final package. The JavaScript files (in concert with HTML/CSS) are what drive the UI anyway.

                                         

                                        As an example, we have a Premiere Pro CEP project that is built using TypeScript for the HTML side (we currently still use TypeScript-service-assisted raw ExtendScript for the app side). The source files are a mixture of JavaScript files (libraries provided by Adobe, e.g. CSInterface.js) and TypeScript files (Vue components, our own libraries, etc.). We use webpack 2 to manage the TypeScript compilation and packaging of all relevant JavaScript into a single "bundle.js" file which is included by our very minimal index.html file. We instruct webpack to output a sourcemap which allows us to map the packaged "bundle.js" back to the original source files for debugging purposes (we use the same setup outlined in the sample).

                                         

                                        In the end, our panel is driven by an 18-line HTML file and a 10,807-line JavaScript file (currently... this has not been minified; still contains comments, etc.).

                                         

                                        I would very much suggest that you make use of static site. In the Angular documentation, they refer to this as AOT (Ahead Of Time compile). In your development environment (your local machine), you can use the latest NodeJS to grab and run development tools using npm. Keep in mind that the CEP Node implementation is very old (io.js 1.2.0, specifically) and does not include npm: it is a running context that provides you with access to the NodeJS API. It's not a Node development environment.

                                         

                                        I hope this helps!

                                        • 17. Re: TypeScript Enabled CEP Development
                                          eyali.av Level 1

                                          Thanks, sberic!

                                          That put me on the right direction, I'll try to configure my environment (VS 2017) to bundle my angular project with AOT (as you suggested).

                                          That's quite a challenge - I still struggle with the entire workflow that contains webpack from an AOT compilation - which are new concepts to me.

                                           

                                          Hopefully, I'll report my progress here. 

                                          • 18. Re: TypeScript Enabled CEP Development
                                            sberic Level 2

                                            eyali.av  wrote

                                             

                                            That put me on the right direction, I'll try to configure my environment (VS 2017) to bundle my angular project with AOT (as you suggested).

                                            That's quite a challenge - I still struggle with the entire workflow that contains webpack from an AOT compilation - which are new concepts to me.

                                            Entirely understood. I've not built an Angular webapp myself, the Vue setup took us a few days to get right. Admittedly, it was our first time using lots of tools (TypeScript+Vue+webpack), so it was a learning experience all around. While there's not much I could add from here, I did find this resource which looks to have a useful Further Reading section. At the very least, I would suggest referring to the webpack 2.0 Configuration Documentation whenever you get stuck. It's the best source of clear and specific webpack information; one that we've referenced quite a bit.

                                             

                                            eyali.av  wrote

                                             

                                            Hopefully, I'll report my progress here. 

                                            Please do! You're almost certainly not the only person interested in using Angular and/or webpack with TypeScript and CEP panels! Best of luck!

                                            • 19. Re: TypeScript Enabled CEP Development
                                              eyali.av Level 1

                                              Thanks, sberic!

                                              I took your advice, and used this resource (this is an 'Hello world' example)   which demonstrate AOT usage and configuration.

                                              It really helped in understanding ngc (this is an alternative compiler which works a lot like tsc and is suitable for the AOT approach) concept and also set-up the npm process (within a package.json file).

                                              The one thing that I managed to change, and I believe can be useful for others is the ability to use a json file as a configuration for the client app (b.t.w - I only refer the HTML code in this reply) - and this can be used to configure settings which ce be changed in runtime for different users/stations. For example, I can set a URL for an API of some kind, of set a user name etc.

                                              • 20. Re: TypeScript Enabled CEP Development
                                                sberic Level 2

                                                eyali.av  wrote

                                                 

                                                The one thing that I managed to change, and I believe can be useful for others is the ability to use a json file as a configuration for the client app (b.t.w - I only refer the HTML code in this reply) - and this can be used to configure settings which ce be changed in runtime for different users/stations. For example, I can set a URL for an API of some kind, of set a user name etc.

                                                That's fantastic! Great job getting it to work! Very glad to hear that you were able to get things working - and in a flexible manner as well!